dbt docs generate: 'NoneType' object is not iterable"

TL;DR

dbt docs generate crashed because the manifest or catalog data it read was malformed or missing, often from stale artifacts or a core/adapter version mismatch. Delete target/, run a fresh dbt compile, then regenerate docs. If it persists, align your adapter version with dbt-core.

Error

"dbt docs generate: 'NoneType' object is not iterable"

Steps

1. Clear stale artifacts: delete the target/ directory in the project. Expected: no old manifest.json or catalog.json remains.
2. Run a fresh dbt compile (or dbt run if you want catalog data from real relations). Expected: compilation succeeds and writes a fresh manifest.
3. Run dbt docs generate. Expected: it completes and writes catalog.json without the NoneType crash.
4. If it still crashes, check versions: dbt --version and confirm the adapter major version matches dbt-core. Expected: versions are aligned.
5. Serve and verify: dbt docs serve, then open the site and confirm models appear. Expected: the docs site renders with content.

When to use

• dbt docs generate crashes with 'NoneType' object is not iterable.
• The crash started after upgrading dbt or switching branches with different artifacts.

When not to use

• Docs generate succeeds but catalog.json is empty (the adapter returned no metadata; check target and permissions).
• The docs site serves but is missing exposures or sources (a definition problem).

Tool compatibility

• dbt Core 1.0 and later, all adapters. Artifact formats are adapter-independent.

Variant phrasings

docs generate crashes after a partial dbt run

A failed run leaves a partial manifest; clearing target and recompiling fixes it.

'NoneType' object has no attribute 'get' during docs generate

Sibling crash from the same family of malformed-artifact problems.

Why it happens

Docs generation walks the manifest and the freshly queried catalog. A manifest from a different dbt version, or a catalog query that returned nothing where a list was expected, produces None where the code iterates.

Edge cases

• Partial parsing can cache a broken manifest; --no-partial-parse on the recompile avoids reusing it.
• Custom generate_docs macros or docs blocks with bad YAML can also crash generation; check recently edited docs blocks.
• Very large projects can exhaust memory during generation; generate on a machine with headroom.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_fH-ZSl4MvjQpZ2yDtZZZjw