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

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