dbt-labs/dbt-core · error

synthetic relation construction should not fail: {e}

Error message

synthetic relation construction should not fail: {e}

What it means

During state-based view traversal, a synthetic BaseRelation is built from a ref FQN and adapter type that were already parsed successfully, so construction is expected to be infallible. If synthetic_relation_from_parts returns Err, an internal invariant is broken (e.g. an adapter type or FQN shape that the synthetic relation builder cannot handle) and the traversal panics to avoid silently skipping relations in the lineage queue.

Source

Thrown at crates/dbt-state/src/view_traversal.rs:321

    view_definitions: &mut BTreeMap<String, Arc<ViewDefinition>>,
    queue: &mut VecDeque<Arc<dyn BaseRelation>>,
    seen_tables: &BTreeSet<String>,
    view_def: &Arc<ViewDefinition>,
    sources_extractor: &dyn SourcesExtractor,
) -> AdapterResult<()> {
    view_definitions.insert(view_def.fqn.clone(), Arc::clone(view_def));
    let refs = extract_referenced_tables(adapter_type, view_def, sources_extractor)?;
    for ref_fqn in refs {
        // `ref_fqn` is a `FullyQualifiedName` with separate catalog/schema/table
        // identifiers. Build a synthetic `BaseRelation` from those parts so
        // the cache key derives from `semantic_fqn()`, matching seed relations.
        match synthetic_relation_from_parts(&ref_fqn, adapter_type) {
            Ok(rel) => {
                if !seen_tables.contains(&rel.semantic_fqn()) {
                    queue.push_back(rel);
                }
            }
            Err(e) => unreachable!("synthetic relation construction should not fail: {e}"),
        };
    }
    Ok(())
}

/// Build a synthetic `Arc<dyn BaseRelation>` from the parsed parts of a
/// `FullyQualifiedName` so its `semantic_fqn()` round-trips to the same
/// cache key seed relations use.
///
/// Returns the underlying `do_create_relation` error if construction fails,
/// so callers can include it in diagnostics.
fn synthetic_relation_from_parts(
    fqn: &FullyQualifiedName,
    adapter_type: AdapterType,
) -> Result<Arc<dyn BaseRelation>, minijinja::Error> {
    let q = dbt_schemas::schemas::common::ResolvedQuoting {
        database: true,
        schema: true,

View on GitHub (pinned to 0267ce9170)

Solutions

1. Check the error text for which adapter_type/FQN part failed and add or fix support for it in synthetic_relation_from_parts.
2. Restrict state comparison to manifests whose nodes all come from supported adapters.
3. Regenerate the manifest with the current dbt version instead of reusing old state artifacts.
4. If the FQN is user-supplied or hand-edited, rebuild it from the node's own identifiers.

if let Err(e) = synthetic_relation_from_parts(&ref_fqn, adapter_type) {
    log::warn!("skipping unconstructable synthetic relation: {e}");
}

fn supports_synthetic_relations(adapter_type: &str) -> bool { /* whitelist of adapters implementing the contract */ }

match synthetic_relation_from_parts(&ref_fqn, adapter_type) {
    Ok(rel) => queue.push_back(rel),
    Err(e) => log::warn!("skipping synthetic relation for {adapter_type}: {e}"),
}

When it happens

Trigger: Calling record_and_enqueue during traverse() with a ref_fqn/adapter_type pair that synthetic_relation_from_parts rejects — e.g. an adapter type without synthetic relation support or a malformed FQN part.

Common situations: Running `dbt clone`/state comparisons across manifests containing nodes from an adapter that doesn't implement the synthetic-relation construction contract; corrupted or hand-edited manifest FQNs; comparing state across dbt versions where FQN shapes changed.

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

• when data_type is date, inner must be a TimeConfig
• ModelPropertiesSemanticModelConfig is never finalized direct
• cannot consume EOF
• Task should always operate on at least a single node
• Task that doesn't belong to a phase should override telemetr

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