debugging-dbt-runslisted

# Debugging dbt Runs ## When to use - `dbt run`/`dbt build` fails or a model errors. - Compilation/Jinja errors, or `ref()` cannot find a model. - An incremental model is stale, missing rows, or has duplicates. - CI dbt job behaves differently from local. - Do NOT use for authoring new models/tests (use the building/testing skills). ## Workflow ``` - [ ] Read the actual error + the compiled SQL (target/compiled/...) - [ ] Classify: compile/Jinja, dependency/DAG, incremental, or env/state - [ ] Reproduce the smallest failing command - [ ] Fix, then re-run just that node with --select ``` 1. **Read the compiled SQL.** dbt writes it to `target/compiled/...`. Most "weird" errors are obvious once you see the rendered SQL, not the Jinja. 2. **Classify the failure** and apply the matching fix below. 3. **Isolate** with `dbt run --select <model>` (and `+model`/`model+` for upstream/downstream) rather than rebuilding everything. 4. **Re-run** the single node to confirm. ## Patterns **Compilation / Jinja** - `dbt compile --select <model>` and open `target/compiled/...` to see rendered SQL. - Undefined variable/macro → check `{{ }}` names, `vars:`, and package installs (`dbt deps`). - "Model depends on a node that was not found" → a `ref()` name typo or the model isn't in a selected path. **Dependency / DAG** - Circular dependency → two models `ref()` each other; break the cycle via an intermediate model. - `dbt ls --select +<model>` shows the upstream graph to tra