What you will be able to do
- Recognise a .yml problem in dbt output as a Compilation Error raised during parsing, and locate the file and line it names
- Tell a YAML syntax error (the file cannot become a dictionary) apart from a schema error (valid YAML with a key dbt does not accept)
- Fix indentation, punctuation, tab and misspelled-key mistakes in properties files and dbt_project.yml
- Avoid file-naming and placement mistakes that stop dbt from reading a properties file at all
Key concept
Two layers of .yml failure — A .yml file can fail in two ways. Either it is not valid YAML, so the parser cannot turn it into a dictionary, or it parses but contains a key that dbt does not accept or is missing a key dbt needs. Which layer failed decides where you look for the fix.
1.Where .yml errors surface in a dbt run
Every .yml file in a dbt project (dbt_project.yml and every properties file that describes models, sources, seeds, snapshots and macros) is read before any SQL is sent to the warehouse. A command such as dbt run goes through a fixed sequence: first it connects, then it parses the project, then it builds the dependency graph, and only then does it run models. Each step has its own error type. A broken .yml file stops the run at the parsing step, so it shows up as a Compilation Error before any model is built.
| Step | What dbt checks | Error type |
|---|---|---|
| Initialize | That this is a dbt project and dbt can connect to the warehouse | Runtime Error |
| Parsing | That Jinja in .sql files is valid and that .yml files are valid | Compilation Error |
| Graph validation | That the dependency graph is acyclic | Dependency Error |
| SQL execution | That the models run | Database Error |
Because the error comes from parsing, it names a file rather than a model. The message dbt prints usually gives both the error type and the file where it happened, so start by opening that file. Reading the rest of the output and the log file is covered in [reading logged error messages](lesson:3.1). Where you are working also changes when you find out. In the Studio IDE, a .yml problem often shows as a red bar in the command prompt while you edit. With dbt Core, nothing is reported until you run dbt run or dbt compile.
Checkpoint 1 of 7· Match them up
Match each step of a dbt run to the error type it raises
Tap a term, then the definition that fits it.
dbt parses .sql Jinja and .yml files before it builds the graph or runs SQL, so an invalid .yml file is reported as a Compilation Error.
“Check that the Jinja snippets in .sql files valid, and that .yml files valid. | Compilation Error”Source: docs.getdbt.com
Checkpoint 2 of 7· Exam question
A `schema.yml` file in `models/staging/` fails to parse with a `Compilation Error`. Given the snippet below (line numbers added for reference), which line causes the YAML compilation error? ``` 1: models: 2: - name: customers 3: columns: 4: - name: customer_id 5: data_tests: 6: - unique ```
Correct answer: C — Line 3 (` columns:`)
- A. The top-level `models:` key is correctly placed at zero indentation and starts the list of model entries as dbt expects. There is nothing malformed about this line on its own.
- B. The list item `- name: customers` sits at a two-space indent directly under `models:`, which is the correct depth for the first key of a model entry. This line parses without issue.
- C. `columns:` is indented six spaces, two more than the four-space depth needed to sit as a sibling of `name` inside the same model entry. That extra indent makes the YAML parser read it as nested under the wrong value, producing the mapping error.
- D. Once the `columns:` line above it is corrected to the right depth, this list item's own indentation relative to `columns:` is consistent, so it is not the line that introduces the parsing failure.
Sources1
2.When the file is not valid YAML
The first layer of failure is plain YAML syntax: the parser cannot turn the file into a dictionary. The most common cause is indentation. In the example below, columns: is indented further than the name: key it belongs beside, so the parser no longer knows which mapping it belongs to.
models:
- name: customers
columns: # this is indented too far!
- name: customer_id
data_tests:
- unique
- not_nullThe error dbt prints has layers, and the labels can mislead you. The outer label is Compilation Error. Inside it, dbt reports which file it was reading, then a Runtime Error with "Syntax error near line 5", and a few numbered lines around that spot. At the bottom, the Raw Error passes on the parser's own message with an exact line and column. The word Runtime here does not mean a connection problem. It is the parser's complaint, wrapped inside a parsing failure.
Compilation Error
Error reading jaffle_shop: schema.yml - Runtime Error
Syntax error near line 5
------------------------------
2 |
3 | models:
4 | - name: customers
5 | columns:
6 | - name: customer_id
7 | data_tests:
8 | - unique
Raw Error:
------------------------------
mapping values are not allowed in this context
in "<unicode string>", line 5, column 12Punctuation causes the same kind of failure. Write description; "A table containing clickstream events..." with a semicolon where the colon should be, and the raw error becomes "while scanning a simple key", with a caret under line 6, column 5. The parser stops recognising the line as a key-value pair. dbt_project.yml breaks in the same ways. A message that starts Could not parse dbt_project.yml: while scanning for... usually points to tab indentation, stray Unicode characters, missing fields or bad formatting. It can also mean the file is missing from the repository altogether.
The fix follows directly from the message. Open the file it names, go to the line and column it reports, and correct the indentation or punctuation there. Turning on indentation guides in your editor helps prevent the problem. A YAML validator can confirm the structure, but don't paste anything sensitive into a third-party website.
Checkpoint 3 of 7· Put it in order
Put the steps for fixing a YAML syntax error in order
- 1.Find the mistake on that line and fix it
- 2.Open the file named in the error message (for example schema.yml)
- 3.Go to the line reported in the error message (for example line 5)
The error already names the file and the line, so you start there instead of searching the whole project.
“Check the line in the error message (e.g. line 5)”Source: docs.getdbt.com
Checkpoint 4 of 7· Exam question
A project's `dbt_project.yml` fails during the parsing phase with `Invalid project config: Additional properties are not allowed`. Given the snippet below (line numbers added for reference), which line is invalid? ``` 1: name: analytics 2: model_paths: ["models"] 3: version: '1.0.0' 4: profile: default ```
Correct answer: B — Line 2 (`model_paths: ["models"]`)
- A. `name` is the one required top-level key in `dbt_project.yml` and is spelled correctly here, so this line is not the source of the error.
- B. `dbt_project.yml` uses dash-separated keys for its top-level configuration, so the correct key is `model-paths`, not `model_paths`. The underscore variant is not part of dbt's schema for this file, which triggers the additional-properties error.
- C. `version` is a recognized top-level key and the quoted string value is valid YAML, so this line parses cleanly.
- D. `profile` is a supported top-level key used to select the connection profile, and the value here is a plain unquoted string, which is valid.
3.When the YAML parses but dbt rejects a key
The second layer of failure is subtler. The file is valid YAML and parses into a dictionary, but the dictionary does not match the structure dbt expects. dbt checks every entry against the properties allowed for that resource type. A model entry, for example, requires name and can also take description, columns, config, constraints, data_tests, versions and a few others. Anything outside that list is rejected.
Encountered an error:
Compilation Error
Invalid models config given in models/schema.yml @ models: {'name': 'customers', 'hello': 'world', 'columns': [{'name': 'customer_id', 'tests': ['unique', 'not_null']}], 'original_file_path': 'models/schema.yml', 'yaml_key': 'models', 'package_name': 'jaffle_shop'} - at path []: Additional properties are not allowed ('hello' was unexpected)These messages are long because dbt prints the whole parsed entry, but the useful part is at the end. A typo can trigger two complaints at once. Write namee: event instead of name: event, and dbt reports both that 'name' is a required property and that 'namee' was unexpected. The real key is missing and the misspelled one is unknown. The same check applies to dbt_project.yml, where a top-level line like hello: world is rejected in the same way.
To fix it, search the named file for the key in quotes and compare it with the property reference for that resource type. Sometimes the key is spelled correctly and appears in the docs, yet dbt still rejects it. In that case, run dbt --version: the key may have been added after the version you have installed. A related warning about unused model configurations in dbt_project.yml usually means the configs aren't nested under the project name, or they point at a directory that doesn't exist. Once the file parses, confirm the fix with the process in [developing and testing a fix](lesson:3.4).
Checkpoint 5 of 7· Fill the gap
Which key makes this model entry valid, so dbt attaches the tests to the order_id column?
- name: stg_jaffle_shop__orders
config:
materialized: view
? :
- name: order_id
data_tests:
- unique
- not_nullcolumns is the model property that holds the list of column definitions. Any other spelling is valid YAML but fails with an 'Additional properties are not allowed' Compilation Error.
Checkpoint 6 of 7· Exam question
A model's `schema.yml` entry raises `Compilation Error: Invalid models config given in models/schema.yml @ models: Additional properties are not allowed ('hello' was unexpected)` because a teammate added a `hello: world` line under a model's properties by mistake. What should the developer do?
Correct answer: B — Remove the `hello` key from the model's YAML entry, since dbt's model-property schema does not recognize keys outside its supported list.
- A. Rebuilding or clearing caches does not address the problem: the error happens during YAML property validation before any SQL is compiled, so nothing about a full-refresh run changes the outcome.
- B. Removing the unrecognized key is correct because the error is a schema-validation failure on the model's properties, not a data or build issue. Once `hello` is gone, the remaining keys match dbt's supported schema and the file parses.
- C. Jinja templating applies to SQL and macro files, not to keys inside a properties file's YAML structure, so wrapping the key in Jinja syntax would itself be invalid YAML and would not resolve the schema mismatch.
- D. `dbt_project.yml`'s `models:` block accepts resource configuration for materializations and similar settings, not arbitrary custom keys either, so relocating `hello` there produces the same additional-properties failure in a different file.
4.File rules that keep dbt reading your properties
Some .yml mistakes produce no error at all, because dbt never opens the file. dbt only looks for files with the .yml extension, so a customers.yaml sitting next to your models is skipped. Location matters too. Model properties belong in the models/ directory. Properties for seeds, snapshots and macros can also go in seeds/, snapshots/ and macros/. The file name, on the other hand, is up to you. schema.yml is only a convention.
A few rules inside the file catch people out. The name of a model entry must match the model's filename exactly, including case. version: 2 at the top is optional from dbt v1.5 onward, but if you include a version: key, 2 is the only supported value. Some properties can only be set in .yml files and not in config() blocks or dbt_project.yml, including columns, description, tests and versions. Put one of these somewhere else and it won't take effect.
Checkpoint 7 of 7· Check yourself
An engineer adds tests in models/marts/customers.yaml. The YAML is valid, but the tests never run and no error appears. What is the most likely cause?
dbt reads only .yml files. Any file name is allowed, version: is optional from v1.5, and properties files can be nested in subfolders.
“At present, dbt will only search for files with a .yml file extension.”Source: docs.getdbt.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.A message that says 'Runtime Error' when reading schema.yml means dbt could not connect to the warehouse.Why is that wrong?
For a broken .yml file, the Runtime Error and 'Syntax error near line N' sit inside an outer Compilation Error raised during parsing. The cause is YAML syntax, often indentation.
Covered in When the file is not valid YAML
2.If a key that appears in the documentation is rejected, it must be a typo.Why is that wrong?
When the key is valid according to the docs, check your installed dbt version. The key may not exist in the version you are running.
Covered in When the YAML parses but dbt rejects a key
3.Properties files must be named schema.yml for dbt to find them.Why is that wrong?
Any name works, as long as the file has a .yml extension and sits in the right resource directory.
4.If a .yml file passes a YAML validator, dbt will accept it.Why is that wrong?
Valid YAML can still fail when dbt checks the structure, for example when a key is unknown or a required key like name is missing.
Covered in When the YAML parses but dbt rejects a key
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://docs.getdbt.com/guides/debug-errorsOfficial docs
“The error message dbt produces will normally contain the type of error”
↩︎ Where .yml errors surface in a dbt run“For dbt v1 users, these won't get picked up until you run dbt run or dbt compile.”
↩︎ Where .yml errors surface in a dbt run“this error often shows as a red bar in your command prompt as you work on your dbt project.”
↩︎ Where .yml errors surface in a dbt run“Usually, it's to do with indentation”
↩︎ When the file is not valid YAML“but there's a key that dbt doesn't recognize.”
↩︎ When the YAML parses but dbt rejects a key“hello: world # this is not allowed”
↩︎ When the YAML parses but dbt rejects a key“dbt wasn't able to turn your YAML into a valid dictionary.”
↩︎ Key concept“Error reading jaffle_shop: schema.yml - Runtime Error”
↩︎ Exam trap 1“If you are using a valid key, check that you're using the latest version of dbt with dbt --version”
↩︎ Exam trap 2“Check that the Jinja snippets in .sql files valid, and that .yml files valid. | Compilation Error”
↩︎ Checkpoint“Check the line in the error message (e.g. line 5)”
↩︎ Checkpoint“Additional properties are not allowed ('hello' was unexpected)”
↩︎ Prediction - 2.https://docs.getdbt.com/reference/define-propertiesOfficial docs
“This error occurred because a semicolon (;) was accidentally used instead of a colon (:) after the description field.”
↩︎ When the file is not valid YAML“There are online YAML validators that can be helpful here, but please be mindful of submitting sensitive information to third-party applications!”
↩︎ When the file is not valid YAML“'name' is a required property, Additional properties are not allowed ('namee' was unexpected)”
↩︎ When the YAML parses but dbt rejects a key“If you're declaring properties for seeds, snapshots, or macros, you can also place this file in the related directory”
↩︎ File rules that keep dbt reading your properties“Must match the filename of a model -- including case sensitivity.”
↩︎ File rules that keep dbt reading your properties“you're still free to name your files schema.yml”
↩︎ Exam trap 3“Here, the name field was provided as namee by accident.”
↩︎ Exam trap 4“At present, dbt will only search for files with a .yml file extension.”
↩︎ Checkpoint - 3.
“There's a parsing failure in a YAML file (such as a tab indentation or Unicode characters).”
↩︎ When the file is not valid YAML - 4.
“You might have forgotten to nest your configurations under your project name”
↩︎ When the YAML parses but dbt rejects a key - 5.https://docs.getdbt.com/reference/model-propertiesOfficial docs
“The model name (must match the model filename).”
↩︎ When the YAML parses but dbt rejects a key - 6.https://docs.getdbt.com/faqs/Project/why-version-2Official docs
“From dbt v1.5, the top-level version: key is optional in all resource YAML files. If present, only version: 2 is supported.”
↩︎ File rules that keep dbt reading your properties