Adovo

Data & Analytics

A successful dbt parse can still lose documentation lineage

Audit manifest doc block references before switching a documentation pipeline to the dbt v2 parser.

November 10, 2026

A parser migration can pass and still degrade the metadata contract. In dbt issue 17025, --use-v2-parser leaves doc_blocks empty on nodes and columns in manifest.json. The rendered descriptions and top-level docs entries still appear, so a basic documentation page check does not expose the missing relationship.

Compare artifacts, not screenshots

Run the same project through both parsers with partial parsing disabled and separate target paths. Inspect a model and column whose description uses doc(), plus one plain-text description. Compare their doc_blocks arrays and rendered text. The issue gives a minimal reproduction with exactly that control case.

dbt's manifest reference explains that the artifact is used by documentation and state consumers, and includes a top-level docs dictionary. A downstream governance tool may need the source-block link even when a human can read the resolved description.

Gate the parser rollout

List consumers that read doc_blocks: lineage, documentation quality checks, ownership reports or internal catalog enrichment. Compare expected references for a representative set before and after the flag. If only rendered descriptions are needed, the impact may be low; if source-block lineage is required, hold the rollout or implement a documented temporary extraction.

Record the parser version with each artifact. A valid JSON schema only proves the field exists, not that its values are complete.

Adovo’s view

Metadata is an interface between teams. A field that silently becomes empty can break trust without breaking a build. Treat artifact parity as a migration test, especially when the visible page still looks fine.

Continue exploring

Data & Analytics

dbtOpenMetadata

A dbt model with no parents can keep old OpenMetadata lineage

Detect stale dbt lineage after a model loses its final upstream dependency despite overrideLineage being enabled.

Read more

Data & Analytics

dbtAnalytics engineering

A dbt parser change can turn a valid test into empty SQL

Compare compiled generic tests before enabling the dbt v2 parser on a production project.

Read more

Data & Analytics

dbt

A dbt private package can work in Cloud and fail on a GHES laptop

Diagnose dbt Fusion private package failures when local resolution points to public GitHub instead of GitHub Enterprise Server.

Read more
Explore data and analytics services →