Fixing YAML that won't compile
YAML compilation errors in dbt usually stem from indentation mistakes, invalid syntax, or misconfigured keys in .yml files, and they surface as parsing errors before dbt even reaches SQL compilation. Because YAML is whitespace-sensitive and dbt enforces a specific schema for properties files, small formatting issues can break dbt parse, dbt compile, or dbt run entirely. Systematic troubleshooting relies on reading the error message closely, validating YAML syntax, and checking dbt's expected schema structure.
1 · Learn the must-know
- dbt error messages typically include the file path and line/column number, so always start by opening the exact file and line referenced in the traceback.
- Common causes include inconsistent indentation (mixing tabs and spaces), missing colons, incorrect list/dict nesting, or duplicate keys under the same model/source entry.
- Running
dbt parseordbt debugisolates whether the issue is YAML syntax versus a Jinja/SQL compilation problem, since parse only validates project structure and config files. - dbt validates .yml files against expected schemas (e.g., models, sources, seeds, snapshots), so using a key in the wrong scope (like putting a source property under a models: block) triggers a validation error even if YAML syntax is valid.
- External YAML linters or an IDE with YAML schema support can catch indentation and syntax errors faster than reading raw dbt tracebacks.
- Version-control diffs are useful for isolating recently introduced YAML errors, since compilation failures often follow directly from the last edited .yml file.
2 · Check your understanding
You add a schema.yml file for a new staging model, then run dbt compile and get a failure.
version: 2
models:
- name: stg_customers
description: "Cleaned customer records"
columns:
- name: customer_id
tests:
- unique
- not_null
- name: stg_customers
description: "Adds email validation"
columns:
- name: email
tests:
- not_null
Terminal output:
Compilation Error
dbt found two resources with the name stg_customers. Since resources
are always uniquely identified by name, this is not allowed.
Why does this compilation error occur?
What you have tried across dbt Analytics Engineering's objectives, not a readiness score.
Developing and optimizing dbt models45.16% of the exam*0 of 14 tried
Managing dbt models governance9.68% of the exam*0 of 3 tried
Debugging data modeling errors16.13% of the exam*0 of 5 tried
Troubleshooting and optimizing dbt pipelines6.45% of the exam*0 of 2 tried
Implementing dbt tests9.68% of the exam*0 of 3 tried
Implementing and maintaining external dependencies6.45% of the exam*0 of 2 tried
Leveraging the dbt state6.45% of the exam*0 of 2 tried
* Our estimate. dbt Labs publishes no section weights.
3 · Keep going
Ready for more? Take a weighted mock or try free practice questions.