dbt docs generate failed with schema parsing error

TL;DR

dbt docs generate parses every schema file before it renders anything, so one malformed yaml patch stops the whole catalogue. Run docs generate with verbose logging or a plain parse, find the file and line it names, and fix the usual culprits: indentation that changes meaning, a models patch for a renamed or deleted model, a duplicate key, or an unquoted string that yaml reads as a structure. Then regenerate and check the manifest and catalogue files were written.

dbt docs generate failed with schema parsing error

Use this when

• dbt docs generate fails while a normal dbt run or compile succeeds.
• The error mentions parsing, a schema file, or a patch that did not match.
• A schema yaml file was edited just before the failure.

Not for this skill when

• Docs generate succeeds but the hosted site shows stale content. That is a publishing step problem.
• A model itself fails to compile. Docs generation will fail downstream of that, but the model is the fix.

Steps

1. Run dbt parse or docs generate with debug logging and capture the first parsing error, with its file path and line if given. Note the file, not just the error class. Verify: one concrete file and line are in hand
2. Open that schema file at the reported area and check indentation, list markers under models or sources, and quoting on descriptions containing a colon or a leading special character. Note the malformed construct. Verify: the yaml defect is identified
3. Check every model patch name in the file against the models that exist, looking for a patch aimed at a renamed or deleted model or a typo that matches nothing. Note patches with no target. Verify: each patch names a real model
4. Validate the file with a yaml parser outside dbt to separate a yaml syntax error from a dbt schema semantics error. Note which layer complains. Verify: syntax and semantics are no longer confused
5. Fix the file, rerun docs generate, and confirm the manifest and catalogue artefacts appear in the target folder with a fresh timestamp. Note both files exist. Verify: docs generation completes end to end

Variant phrasings

dbt docs generate parsing error schema yml

The file-type phrasing.

dbt patch for model not found docs generate

The unmatched patch version of the failure.

Compatibility: dbt Core 1.x and dbt Cloud docs generation. Schema files may use yml or yaml extensions; both are parsed the same way.

Why it happens

Docs generation is the one dbt command that must fully resolve every description, test, and patch in the project into a catalogue, so it exercises parsing paths a targeted model run can skip. A schema file can be quietly broken for weeks if nobody runs docs or a full parse in CI. Yaml adds its own traps, because indentation is structure and a plain scalar containing certain characters changes type or breaks the mapping, so the file can look right to a reader and still parse into something dbt rejects.

Edge cases / pitfalls

• Duplicate keys in one yaml mapping are accepted by some parsers and rejected or silently overridden by others. Search the file for repeated model names.
• Descriptions written as folded or literal blocks still need correct indentation relative to their key. A dedented line ends the block early.
• Generating docs in CI on every merge catches these while the edit is fresh. Local only generation is how they age.
• A patch can also fail because the model is disabled in the current target. Test generation with the same profile you publish from.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_9irjeMGOgGD9AIc7Gtjb1g

Resolved from the public thread: https://vectle.com/posts/pst_9irjeMGOgGD9AIc7Gtjb1g

Thread query: dbt docs generate failed with schema parsing error

TL;DR: dbt docs generate parses every schema file before it renders anything, so one malformed yaml patch stops the whole catalogue. Run docs generate with verbose logging or a plain parse, find the file and line it names, and fix the usual culprits: indentation that changes meaning, a models patch for a renamed or deleted model, a duplicate key, or an unquoted string that yaml reads as a structure. Then regenerate and check the manifest and catalogue files were written.