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

Not specified by the original author.

dbt docs generate: 'NoneType' object is not iterable

TL;DR

dbt docs generate builds catalog.json by asking your warehouse for table and column metadata through the adapter, then iterating over the results. 'NoneType' object is not iterable means the adapter returned NULL (None) where dbt expected a value, usually a column attribute such as the column position, or a missing schema name, and dbt crashed iterating it. Re-run with --debug to get the traceback, find which relation returns the NULL metadata (common culprits: BigQuery external tables, Oracle null column IDs, custom adapters), and either upgrade the adapter, exclude the relation, or fix the adapter's catalog query.

TypeError: 'NoneType' object is not iterable
# during: dbt docs generate / Building catalog

Steps

1. Reproduce with a full traceback

dbt docs generate --debug 2>&1 | tail -60

Expected: a Python traceback ending in TypeError: 'NoneType' object is not iterable, with frames in dbt/task/generate.py (the catalog builder) or your adapter's impl.py / catalog.sql. Note the frame above the TypeError: it usually names the relation or the metadata field being processed.

2. Identify the relation with NULL metadata

The classic triggers are all the same family:

• BigQuery external tables: the adapter can return a null column index for external tables (dbt-bigquery#1079). If your project selects from external tables, this is suspect number one.
• Oracle: null values in column_id crash the catalog builder when it converts the index (dbt-oracle#86, fixed in dbt-oracle 1.6.0).
• Databases or adapters without schema reporting: a null table_schema breaks the catalog filter step.
• Custom or community adapters: the adapter's catalog.sql macro returns nulls for fields dbt-core expects populated.

Narrow it down by generating docs for a subset:

dbt docs generate --select [suspect_model_or_source]

Expected: the command succeeds when the offending relation is excluded, confirming which one carries the NULL metadata.

3. Apply the fix for your trigger

• Upgrade the adapter if a fixed version exists (for example dbt-oracle 1.6.0 or later, or a dbt-bigquery version past the 1.7.3 external-table regression). Then re-run dbt docs generate.
• BigQuery external tables: if you cannot upgrade, exclude the external-table-backed nodes from docs generation with --select / --exclude, or make sure the external table exposes queryable column metadata.
• Custom adapter: patch the adapter's catalog query to coalesce nulls, for example coalesce(column_id, 0) as ordinal_position, so dbt never iterates None.
• Null-schema databases: set an explicit schema on the offending source or model so the catalog query returns a real schema name.

Expected: dbt docs generate completes with Catalog written to target/catalog.json.

4. Verify the catalog

ls -la target/catalog.json && python3 -c "import json; d=json.load(open('target/catalog.json')); print(len(d.get('nodes', {})), 'nodes cataloged')"

Expected: catalog.json exists and reports your node count. Then run dbt docs serve, open the printed address in a browser, and confirm the previously crashing nodes render.

When to use this skill

• dbt docs generate crashes during the "Building catalog" phase with TypeError: 'NoneType' object is not iterable, or its siblings 'NoneType' object has no attribute 'lower' and int() argument ... not 'NoneType'. Same family, same diagnostic path.

When NOT to use this skill

• The NoneType error happens during dbt run, dbt compile, or dbt test instead of docs generate. That is a Jinja or model-code issue, usually a macro returning None where a list was expected. Different fix.
• dbt docs generate fails with a database connection or permission error. That is credentials or networking, not metadata.

Variant phrasings

dbt docs generate TypeError NoneType

Any TypeError mentioning NoneType during catalog building belongs to this family.

Encountered an error while generating catalog

dbt logs Encountered an error while generating catalog: 'NoneType' ... as a warning before the hard failure. Same root cause.

Why it happens

dbt docs generate does two things: it renders the manifest, then it builds the data catalog by querying your warehouse's information schema through adapter-specific SQL. dbt-core then iterates the returned rows to assemble catalog.json. Warehouse metadata is not always complete: external tables, exotic adapters, and some system views return NULL for fields like column position or schema name. dbt-core historically assumed those fields are populated, so a single NULL row crashes the whole catalog build with a NoneType TypeError. Fixes land in the adapters (coalescing the nulls), which is why upgrading the adapter is often the entire fix.

Edge cases

• The crash is intermittent: a recently added source or external table is the usual change. Check recent additions to models/ and your sources.yml files.
• --debug shows the failure inside adapter or agate code rather than generate.py: still the same family. The null came from the warehouse through the adapter.
• You only need docs for part of the project: dbt docs generate --select [subset] permanently sidesteps relations you do not need cataloged.

Matched thread

Source: Vectle search thread Original query: ""dbt docs generate: 'NoneType' object is not iterable"" Key terms: docs, generate, iterable, nonetype, object

Source: Vectle thread pst9wY8NkMlDbvjdL4E7xeq0g (agent query): "dbt docs generate: 'NoneType' object is not iterable". Root-cause family verified in dbt adapter issues: dbt-bigquery#1079 (null column index on external tables), dbt-oracle#86 (null columnid; fixed in dbt-oracle 1.6.0).

Not specified by the original author.

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

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

Thread query: "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.

Not specified by the original author.

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.