dbt docs site shows stale model descriptions after deploy

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Run dbt docs generate to build the project documentation as static files, then dbt docs serve to browse them locally. For a team, generate in CI and host the static site somewhere everyone can reach. The docs include model descriptions, column tests, and the full lineage graph, which is the fastest way to answer what a table means and where it comes from.

The query

dbt docs generate and serve

Use this when

• New team members ask what a model does or where data comes from
• You want a browsable lineage graph of the project
• Stakeholders need a self-serve reference for table definitions

Not for

• Enforcing who can see what (docs have no access control)
• Live data quality dashboards
• Documenting pipelines that are not in dbt

Steps

1. Add descriptions to your models and columns in the schema YAML. Generated docs are only as good as the descriptions; undocumented models produce an empty-looking site.

Expected output: key models have description fields that a newcomer can understand.

2. Generate the docs artifacts:

dbt docs generate

Expected output: target/catalog.json, target/manifest.json, and target/index.html appear in the project.

3. Serve locally to preview:

dbt docs serve --port 8080

Expected output: the docs site opens in a browser with the lineage graph and model pages.

4. Host it for the team. Generate in CI on merge to main, upload the target artifacts to static hosting (S3, GCS, Netlify, or internal), and link it from the team wiki. Refresh on every merge so docs never go stale.

Expected output: a stable URL the whole team uses, rebuilt automatically on every merge.

Provenance

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

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

Thread query: dbt docs generate and serve

TL;DR: Run dbt docs generate to build the project documentation as static files, then dbt docs serve to browse them locally. For a team, generate in CI and host the static site somewhere everyone can reach. The docs include model descriptions, column tests, and the full lineage graph, which is the fastest way to answer what a table means and where it comes from.

Not specified by the original author.

TL;DR

dbt docs generate parses every schema file before it renders anything, so one malformed yaml patch stops the whole catalogue. Run docs generate with verbose logging or a plain parse, find the file and line it names, and fix the usual culprits: indentation that changes meaning, a models patch for a renamed or deleted model, a duplicate key, or an unquoted string that yaml reads as a structure. Then regenerate and check the manifest and catalogue files were written.

dbt docs generate failed with schema parsing error

Use this when

• dbt docs generate fails while a normal dbt run or compile succeeds.
• The error mentions parsing, a schema file, or a patch that did not match.
• A schema yaml file was edited just before the failure.

Not for this skill when

• Docs generate succeeds but the hosted site shows stale content. That is a publishing step problem.
• A model itself fails to compile. Docs generation will fail downstream of that, but the model is the fix.

Steps

1. Run dbt parse or docs generate with debug logging and capture the first parsing error, with its file path and line if given. Note the file, not just the error class. Verify: one concrete file and line are in hand
2. Open that schema file at the reported area and check indentation, list markers under models or sources, and quoting on descriptions containing a colon or a leading special character. Note the malformed construct. Verify: the yaml defect is identified
3. Check every model patch name in the file against the models that exist, looking for a patch aimed at a renamed or deleted model or a typo that matches nothing. Note patches with no target. Verify: each patch names a real model
4. Validate the file with a yaml parser outside dbt to separate a yaml syntax error from a dbt schema semantics error. Note which layer complains. Verify: syntax and semantics are no longer confused
5. Fix the file, rerun docs generate, and confirm the manifest and catalogue artefacts appear in the target folder with a fresh timestamp. Note both files exist. Verify: docs generation completes end to end

Variant phrasings

dbt docs generate parsing error schema yml

The file-type phrasing.

dbt patch for model not found docs generate

The unmatched patch version of the failure.

Compatibility: dbt Core 1.x and dbt Cloud docs generation. Schema files may use yml or yaml extensions; both are parsed the same way.

Why it happens

Docs generation is the one dbt command that must fully resolve every description, test, and patch in the project into a catalogue, so it exercises parsing paths a targeted model run can skip. A schema file can be quietly broken for weeks if nobody runs docs or a full parse in CI. Yaml adds its own traps, because indentation is structure and a plain scalar containing certain characters changes type or breaks the mapping, so the file can look right to a reader and still parse into something dbt rejects.

Edge cases / pitfalls

• Duplicate keys in one yaml mapping are accepted by some parsers and rejected or silently overridden by others. Search the file for repeated model names.
• Descriptions written as folded or literal blocks still need correct indentation relative to their key. A dedented line ends the block early.
• Generating docs in CI on every merge catches these while the edit is fresh. Local only generation is how they age.
• A patch can also fail because the model is disabled in the current target. Test generation with the same profile you publish from.

Provenance

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

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

Thread query: dbt docs generate failed with schema parsing error

TL;DR: dbt docs generate parses every schema file before it renders anything, so one malformed yaml patch stops the whole catalogue. Run docs generate with verbose logging or a plain parse, find the file and line it names, and fix the usual culprits: indentation that changes meaning, a models patch for a renamed or deleted model, a duplicate key, or an unquoted string that yaml reads as a structure. Then regenerate and check the manifest and catalogue files were written.