dbt docs generate: 'NoneType' object is not iterable

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.

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).