Debugging Data Modeling Errors Study Guide — dbt Analytics Engineering Certification

Debugging Data Modeling Errors

This domain (~13% of the exam, roughly 8–10 scored questions on a typical form) tests whether you can look at raw dbt output — an error banner, a stack of Jinja frames, a dbt debug report, or a chunk of logs/dbt.log — and immediately say what stage of the dbt lifecycle failed, why, and which command or config fixes it. Questions are overwhelmingly scenario-based: you are shown an error string and asked for the cause or the next action. The exam rewards precise vocabulary (Parsing Error vs Compilation Error vs Database Error vs Runtime Error), knowledge of where dbt writes artifacts (target/compiled, target/run, logs/dbt.log, run_results.json), and the small set of CLI flags that make debugging faster (dbt compile, dbt debug, dbt parse, --select, --full-refresh, --fail-fast, --debug). Supported version for the exam is dbt 1.11.

Reading dbt compile/run error output: compilation vs database errors

Every dbt invocation moves through fixed stages. The stage at which an error is raised determines the error class, and the error class tells you where to look. Memorize this ordering — it is the single most reusable fact in the domain.

Where each error class is raised during a dbt invocation

Anatomy of the error banner

Database Error in model dim_customers (models/marts/dim_customers.sql)
  001003 (42000): SQL compilation error:
  syntax error line 12 at position 4 unexpected 'form'.
  compiled Code at target/run/jaffle_shop/models/marts/dim_customers.sql

• Line 1 = error class + resource type + resource name + source file path.
• Middle = the verbatim message. If it carries a vendor error code (Snowflake 001003, BigQuery Syntax error:, Postgres SQLSTATE 42703), it is a Database Error, no matter what the word "compilation" appears inside it. Snowflake calls its own parse failures "SQL compilation error" — that is still a dbt Database Error. This is the exam's favourite distractor.
• Last line = pointer to the artifact. target/run/... for executed nodes (includes the create table as wrapper); target/compiled/... for dbt compile and ephemeral/test nodes.

Compilation vs Database at a glance

Statuses, skips, and exit codes

• A failed model causes all downstream children to be skipped, not failed. The summary reads Done. PASS=... WARN=... ERROR=... SKIP=... TOTAL=....
• Exit code 0 = success; 1 = handled failure (model error, test failure); 2 = unhandled exception / bad usage.
• --fail-fast (-x) aborts the whole run at the first node failure instead of finishing the rest of the DAG.
• dbt retry re-executes only the nodes that errored or were skipped in the previous invocation, using target/run_results.json. It cannot be used after you change selection logic arbitrarily — it replays the prior run's state.
• --warn-error promotes every warning to an error; --warn-error-options scopes that to named warning types.

Common traps

• Treating "SQL compilation error" from Snowflake as a dbt Compilation Error. It is a Database Error.
• Assuming dbt compile would have caught a bad column name. It would not — unknown columns are only discovered by the warehouse at run time.
• Thinking downstream models "fail" when a parent errors; they are skipped and reported in SKIP.
• Believing a non-zero exit code always means a model broke; a failing test also exits 1.
• Assuming errors abort the run. By default dbt continues building unrelated branches of the DAG unless --fail-fast is set.

Worked scenario. A run reports ERROR=1 SKIP=7. The error text is Compilation Error in model stg_orders … Model 'model.jaffle.stg_payments' was not found or is disabled. Do you check the warehouse grants, the SQL, or the YAML? The YAML — the message is a Compilation Error naming a missing/disabled node, which means stg_payments is either absent, misspelled in ref, or has enabled: false (often via a +enabled: "{{ target.name == 'prod' }}" config that evaluates false in your target).