## 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

```text
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