dbt-labs/dbt-core · error

Failed to create relations from nodes

Error message

Failed to create relations from nodes

What it means

During `docs generate` catalog writing, relations are rebuilt from resolved manifest nodes (seeds/models/snapshots) via an adapter relation constructor, and any construction failure is turned into a panic with this message. It means one of the node's database/schema/alias/quoting components could not be turned into a valid relation by the adapter (e.g. an adapter that doesn't support the operation or an invalid identifier).

Source

Thrown at crates/dbt-main/src/compilation.rs:2772

        )
        .chain(
            resolved_state
                .nodes
                .sources
                .values()
                .map(|n| &n.__base_attr__),
        )
        .map(|base| {
            Arc::from(
                create_relation(
                    resolved_state.adapter_type,
                    base.database.clone(),
                    base.schema.clone(),
                    Some(base.alias.clone()),
                    None,
                    base.quoting,
                )
                .expect("Failed to create relations from nodes"),
            )
        })
        .collect::<Vec<_>>();
    write_catalog_json(
        &adapter,
        resolved_state,
        relations,
        jinja_env.as_ref(),
        project_name,
        &base_context,
        arg,
        20,
    )
    .await
}

/// Check if a select expression matches any macro's file path.
/// Returns the matched selector value if a macro was matched.

View on GitHub (pinned to 0267ce9170)

Solutions

  1. Re-run `dbt docs generate` after a clean `dbt clean` + `dbt build` so resolved_state nodes have complete database/schema/alias
  2. Verify the adapter crate is up to date and supports relation construction for your node types
  3. Check profile/database/schema quoting configuration for empty or invalid identifiers
  4. Run with RUST_BACKTRACE=1 to find which node fails and fix that node's config or database/schema

Example fix

// before
BaseRelation::from(
    adapter, base.database.clone(), base.schema.clone(), Some(base.alias.clone()), None, base.quoting,
).expect("Failed to create relations from nodes")
// after: log node id and skip/fail with context
let relation = BaseRelation::from(...)
    .map_err(|e| anyhow!("failed to build relation for node {}: {e}", base.identifier))?;
Defensive patterns

Strategy: validation

Validate before calling

// validate node identity parts before building relations
for node in nodes {
    if node.database.is_none() || node.schema.is_none() || node.alias.is_none() {
        return Err(format!("node {} missing database/schema/alias", node.unique_id));
    }
}

Try / catch

let relation = BaseRelation::from(...).map_err(|e| anyhow!("node {}: {e}", node.unique_id))?;

Prevention

When it happens

Trigger: Running `dbt docs generate` where `write_catalog_json` iterates `resolved_state` nodes and calls the adapter's relation constructor with a node whose database/schema/alias is None or invalid, or where the adapter returns Err (e.g. unsupported adapter feature or bad quoting config).

Common situations: Custom/partial adapters whose `relation_from_node`-style API returns Err; nodes with empty database or schema after profile changes; renamed quoting settings in dbt_project.yml/profile; stale resolved_state mixing adapters.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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