dbt docs serve: Exploring Your Project’s Interactive Documentation

Generating documentation artifacts with dbt docs generate is only useful once you can actually browse them. dbt docs serve spins up a local web server hosting the generated documentation site, turning the manifest.json and catalog.json files covered in dbt docs generate into an interactive, clickable interface for exploring your project.

Running It Locally

dbt docs generate
dbt docs serve

By default, this opens a documentation site at http://localhost:8080. The order matters — docs serve displays whatever was most recently generated; running serve without first running generate will show stale or empty documentation from an earlier run.

# Custom port, useful if 8080 is already in use
dbt docs serve --port 8081

What You Can Actually Do in the Documentation Site

Search across the entire project. A search bar lets you find any model, source, or macro by name — far faster than grepping through files manually when you’re unfamiliar with a large project’s structure.

Browse model details. Clicking any model shows its description, columns (with their individual descriptions and configured tests), materialization type, and the raw and compiled SQL side by side.

Explore the lineage graph. Every model has a lineage view showing its upstream and downstream dependencies, filterable by how many hops away you want to see — the visual counterpart to the dbt ls --select model+ command-line queries covered in Data Lineage (DAG).

Inspect column-level lineage (where supported by your adapter) — not just which models depend on which, but which specific upstream column a given output column was derived from.

Using the Lineage Graph for Onboarding

The single most valuable use of dbt docs serve for a new team member isn’t reading individual model descriptions — it’s clicking through the lineage graph starting from a model they already recognize (a dashboard’s source table, for instance) and tracing backward through staging models to understand how raw data actually becomes that number. This turns “how does this pipeline work” from a question that requires asking a teammate into something explorable independently.

Full-Text Search Across Compiled SQL

Beyond model names, the documentation site’s search covers descriptions and, in most setups, searchable metadata across the whole project — useful for answering questions like “which models reference this specific column name” without manually grepping every SQL file in the repository.

Hosting docs serve for a Whole Team, Not Just Locally

dbt docs serve as shown above is meant for local, individual use — it’s not designed to be a persistent, shared service. For team-wide access, the standard pattern is generating the static artifacts in CI and hosting them somewhere durable, rather than every team member running their own local server.

# CI step: generate once, host the static output for everyone
dbt docs generate
aws s3 sync target/ s3://internal-docs-bucket/dbt-docs/ --delete

dbt Cloud provides this as a built-in hosted feature; self-managed setups typically use a static file host (S3 + CloudFront, an internal file server, or a simple Nginx container serving the target/ directory) behind whatever access control the organization already uses for internal tools.

Keeping the Served Docs in Sync With Reality

A documentation site is only as trustworthy as how recently it was regenerated. If it’s hosted centrally rather than generated on demand locally, it needs to be part of the regular deployment pipeline — regenerated every time models change, not as an occasional manual task someone remembers to do.

# Example: docs regeneration as part of every production deploy
production_deploy:
  steps:
    - dbt build
    - dbt docs generate
    - upload_docs_to_hosting

Using the Documentation Site During Code Review

A less obvious but genuinely useful habit: before approving a pull request that adds a new model, open the local documentation site and click through to that model’s entry — checking that its description, column documentation, and configured tests actually render as expected, not just that the YAML syntax happened to be valid. This catches a specific and common mistake: a description or test attached to the wrong column name due to a copy-paste error, which YAML validation alone won’t flag since the file is still syntactically correct, just semantically wrong.

Troubleshooting a Blank or Broken Docs Site

Error: could not find manifest.json in target/

This means dbt docs serve was run without a prior dbt docs generate in the same target/ directory — the two commands are separate steps, and serve doesn’t implicitly generate anything itself.

If the site loads but shows outdated information (a model you know you renamed still shows its old name), it almost always means dbt docs generate needs to be re-run — the site reflects whatever was captured at generation time, not the current state of your files.

Common Mistakes

Running docs serve without first running docs generate. This is the most common source of confusion for anyone new to the command — always generate before serving, and regenerate after any project change you want reflected.

Assuming a locally-run docs serve is accessible to the rest of the team. It’s a local server bound to your machine by default — team-wide access requires hosting the generated static files somewhere shared, not just running serve on your own laptop.

Letting a centrally-hosted docs site go stale. If regeneration isn’t wired into the deployment pipeline, the hosted documentation silently drifts out of sync with the actual project, which is worse than having no shared documentation at all since people trust it by default.

Summary

dbt docs serve turns the metadata dbt already tracks into something genuinely explorable — the fastest way for anyone, new or experienced, to answer “how does this actually work” about a project they didn’t build themselves.