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.

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