dbt-labs/dbt-core · error · InvalidOperation

Documentation depends on doc '{doc_name}' which was not foun

Error message

Documentation depends on doc '{doc_name}' which was not found

What it means

doc() resolves the requested doc name (and optional package) against the manifest's documentation blocks. In strict mode, when no matching doc block exists, this error mirrors dbt-core's DocTargetNotFoundError instead of silently rendering nothing.

Source

Thrown at crates/dbt-jinja-utils/src/functions/base.rs:284

                    .package_search_order
                    .iter()
                    .find_map(|package_name| self.lookup_doc(package_name, &arg1))
                    .or_else(|| self.lookup_doc_in_packages(&arg1));
                (
                    doc,
                    self.package_search_order
                        .first()
                        .cloned()
                        .unwrap_or_default(),
                    arg1,
                )
            }
        };

        match doc {
            Some(content) => Ok(Value::from_serialize(content)),
            // `DocTargetNotFoundError`
            None if self.strict => Err(Error::new(
                ErrorKind::InvalidOperation,
                format!("Documentation depends on doc '{doc_name}' which was not found"),
            )),
            None => {
                let current_span = state.current_span_of_context();
                let current_file_path = state.current_path().clone();
                if !current_file_path.as_os_str().is_empty() {
                    let location = CodeLocationWithFile::new(
                        current_span.start_line,
                        current_span.start_col,
                        current_span.start_offset,
                        current_file_path,
                    );
                    Self::warn_missing_doc(&target_package, &doc_name, location);
                }
                Ok(Value::from(Self::missing_doc_placeholder(
                    &target_package,
                    &doc_name,

View on GitHub (pinned to 0267ce9170)

Solutions

Check the spelling of the doc name against the docs blocks defined in markdown files.
If using {{ doc('pkg', 'name') }}, verify the package name and that it declares the doc block.
Add the missing dbt package to packages.yml and run dbt deps.
Recreate the removed/renamed doc block or update all references to it.

Example fix

// before
{{ doc('order_staus') }}
// after
{{ doc('order_status') }} // matches {% docs order_status %}...{% enddocs %}

Defensive patterns

Strategy: validation

Validate before calling

// before rendering, check the doc block exists in the manifest
// grep -r '{% docs order_status %}' . || echo 'doc block missing'

Try / catch

// strict mode surfaces DocTargetNotFoundError; catch at render boundary and log the doc_name for triage

Prevention

Cross-check doc names against defined {% docs %} blocks in markdown files.
Verify package-qualified references exist in dependencies declared via packages.yml.
Run dbt compile/parse in CI to catch dangling doc references before release.

When it happens

Trigger: {{ doc('some_doc') }} where some_doc is not defined in the project or referenced packages, or the package-qualified name {{ doc('pkg', 'doc') }} points to a package without that doc block.

Common situations: Typo in the doc name, doc block removed or renamed, missing dependency package in packages.yml, wrong package name in the two-argument form.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of dbt-labs/dbt-core@0267ce9170 (2026-09-07). Data as JSON: /api/errors/78da8a830d018938. Report an issue: GitHub.