dbt docs site shows stale model descriptions after deploy

TL;DR

The docs site is serving an old generated bundle: either docs generate did not rerun in the deploy, or the host cached the old index and catalog. Regenerate docs from the current manifest, redeploy the full target output together (index.html, manifest.json, catalog.json), and bust the host cache. Descriptions live in the generated files, not in the warehouse.

dbt docs site shows stale model descriptions after deploy

Use this when

• model descriptions changed in YAML but the docs site shows the old text after deploy
• new models appear but their descriptions or columns are outdated
• docs look current locally but stale on the hosted site

Not for this skill when

• docs generate fails outright, fix generation first
• descriptions are wrong in the YAML itself, edit the source of truth
• you expect descriptions from the warehouse to sync automatically, dbt docs does not work that way

Steps

1. Confirm the source: grep the current YAML for the new description text and check its commit is in the deployed branch. Verify: the new description exists in the code being deployed.

2. Run dbt docs generate locally on that code and search the generated catalog or index bundle for the new text. Verify: the freshly generated docs contain the new description, proving generation works.

3. Compare what the host serves: note whether the deploy uploads the whole target output or a subset. Redeploy index.html, manifest.json, and catalog.json as one set with matching timestamps. Verify: the hosted files are one consistent generated set.

4. Hard refresh and check the hosted site in a private window; if still stale, purge the CDN or static host cache for the docs path and recheck. Verify: the hosted docs show the new description without cache tricks.

Variant phrasings

descriptions stale, lineage current

Partial uploads update some files but not others. The mismatch pattern tells you which file the deploy missed; make the upload atomic.

dbt Cloud hosted docs stale

Cloud docs reflect the last job that produced artifacts with docs steps. Run a job that includes docs generate, not just run and test steps.

Compatibility: dbt docs generate static site (index.html plus manifest.json and catalog.json) hosted on any static host or dbt Cloud. Description text comes from YAML properties at generate time.

Why it happens

The docs site is a static snapshot built at generate time. Nothing in it polls the repo or warehouse afterwards. If the deploy pipeline skips generation, uploads a partial file set, or a cache keeps serving the previous bundle, the site faithfully shows old descriptions until a complete fresh bundle replaces it.

Edge cases / pitfalls

• Search engines and AI tools may cache the old page longer than your host does; verify with a direct fetch, not a search result.
• Persisting descriptions to the warehouse (persist_docs) is a separate feature and does not update the docs site.
• Timestamp skew between manifest and catalog from different runs produces subtler staleness; always ship one run output.

Provenance

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

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

Thread query: dbt docs site shows stale model descriptions after deploy

TL;DR: The docs site is serving an old generated bundle: either docs generate did not rerun in the deploy, or the host cached the old index and catalog. Regenerate docs from the current manifest, redeploy the full target output together (index.html, manifest.json, catalog.json), and bust the host cache. Descriptions live in the generated files, not in the warehouse.