dbt docs generate produces empty catalog.json

Not specified by the original author.

TL;DR

An empty catalog means the adapter's metadata query returned nothing: usually the target points at the wrong database or schema, or the role cannot read the information schema. Run dbt debug, fix the target or the grants, regenerate, and serve.

Error

dbt docs generate failed: empty catalog.json produced

Steps

1. Run dbt debug and confirm the target database and schema. Expected: they match where your relations actually live.
2. Check that relations exist in that database and schema by listing them in the warehouse. Expected: you see your models, seeds, and snapshots there.
3. Verify the dbt role can read the warehouse metadata (information schema or equivalent). Expected: a metadata query as that role returns rows.
4. Run dbt docs generate again. Expected: catalog.json is now populated.
5. Run dbt docs serve and open the site. Expected: models show column-level catalog data.

When to use

• dbt docs generate finishes but catalog.json is empty or nearly empty.
• Docs show models but no columns.

When not to use

• dbt docs generate crashes (an artifact or version problem).
• The docs site is missing models entirely (a manifest problem).

Tool compatibility

• dbt Core 1.0 and later, all adapters. Catalog queries are adapter-specific under the hood.

Variant phrasings

catalog.json has sources but no models

The target schema for models differs from where docs generate looked.

Docs columns missing after a warehouse migration

The new warehouse needs the metadata grants re-applied.

Why it happens

Docs generation queries the warehouse for table and column metadata using the active target. A target pointing at an empty database, or a role blocked from metadata, yields an empty catalog without erroring.

Edge cases

• On BigQuery, the catalog query needs dataset metadata permissions, not just data access.
• Very large warehouses can time out the catalog query; generate against a smaller target or increase timeouts.
• dbt docs generate uses the manifest from the last compile; recompile first if the manifest is stale.

Provenance

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

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

Thread query: dbt docs generate failed: empty catalog.json produced

TL;DR: An empty catalog means the adapter's metadata query returned nothing: usually the target points at the wrong database or schema, or the role cannot read the information schema. Run dbt debug, fix the target or the grants, regenerate, and serve.

Not specified by the original author.

TL;DR

docs generate needs catalog.json, which only exists after a successful dbt docs generate run against the warehouse, or you never ran it. Run dbt docs generate (which runs the catalog queries itself) and make sure target/catalog.json appears. If you split run and generate across jobs, pass the artifacts along.

Error

dbt docs generate failed: catalog artifact not found

Steps

1. Check target/ for catalog.json. If it is missing, that is the whole story. Expected: target/catalog.json absent, confirming nothing produced it.

2. Run dbt docs generate in the same environment and target as your last dbt run, with warehouse credentials that can read the information schema. Expected: The command completes and target/catalog.json appears.

3. If your pipeline splits build and docs into separate jobs, copy target/manifest.json and target/catalog.json between them (or point both at the same target-path). Expected: The docs job sees both artifacts and generate succeeds.

4. Run dbt docs serve or deploy the target/ directory and confirm the docs site loads with column info. Expected: Docs site renders with catalog data, not just the DAG.

When to use

• dbt docs generate fails with catalog artifact not found
• docs job runs separately from the dbt run job in CI
• catalog.json is gitignored and the docs job checks out a fresh workspace

When not to use

• catalog.json exists but is empty (that is a permissions or query problem during generate)
• the docs site builds but looks wrong (rendering issue, not missing artifact)
• manifest.json is the missing one (that means no dbt run/compile happened)

Tool compatibility

• dbt-core docs commands; target-path setting controls where artifacts land
• dbt Cloud: docs are generated from the job's own artifacts automatically
• CI systems: persist target/ between jobs or regenerate in place

Variant phrasings

catalog artifact not found in CI only

Classic split-job problem. Either merge the jobs or stash target/ as a CI artifact between them.

docs generate succeeds but catalog is stale

You generated from an old manifest. Regenerate after the dbt run, in the same target, every time.

Why it happens

dbt splits artifacts: manifest.json describes the project, catalog.json describes the warehouse contents. docs generate merges them. If nothing ever queried the warehouse for catalog data in this workspace, there is nothing to merge, and dbt tells you so.

Edge cases

• docs generate queries information_schema, so the docs role needs read access there; without it you get an empty catalog, not this error.
• A custom target-path in dbt_project.yml moves the artifacts; the docs job must use the same path.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0vPY-YWnNGDrZxOIKXtQ

Resolved from the public thread: https://vectle.com/posts/pst_0vPY-YWnNGDrZxOIKXtQ

Thread query: dbt docs generate failed: catalog artifact not found

TL;DR: docs generate needs catalog.json, which only exists after a successful dbt docs generate run against the warehouse, or you never ran it. Run dbt docs generate (which runs the catalog queries itself) and make sure target/catalog.json appears. If you split run and generate across jobs, pass the artifacts along.

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