Diagnose compilation context and relation resolution

Understand the likely causes

• Resource indentation or config scope can be wrong before SQL exists. Template values and execute-time results differ, and a ref hidden during parsing can be absent from dependency discovery. After rendering, target schema, deferral and runtime privileges can still differ from an interactive administrator’s context.

Identify the first failing boundary

Classify the error as resource/YAML parsing, Jinja rendering, graph resolution, SQL analysis or target execution. Keep the original file path and line from approved evidence, but redact secrets and private endpoints. A relation error cannot be repaired by changing YAML indentation if the resource already rendered correctly; an undefined macro is not automatically a missing warehouse grant. Confirm whether the project uses the v1.12 teaching generation or v2, since file-context support and validation differ. No diagnostic dbt command is invoked by this guide.

Inspect arguments and phase-dependent logic

In the fragment, known_flag receives a quoted Jinja string that becomes a trusted SQL expression. Without quotes, returned_at would be looked up as a template variable. This is not SQL parameter binding for arbitrary user text. If a macro uses run_query, protect parse-time logic with the supported execute context and keep required dependencies visible. A successful delimiter check does not prove dbt parsing, and a compilation-oriented command can still contact the warehouse through introspection. The example is not rendered or executed here.

select {{ known_flag('returned_at') }} as has_return
from {{ ref('stg_loans') }}

Compare logical references with resolved relations

Inspect the declared source or model, package namespace, target schema and any state/defer context in existing approved artifacts. The local review JSON names evidence categories rather than a live connection. A source declaration does not create its relation, and ref does not universally mean the developer’s own schema. A working administrator query may use different ownership and privileges. Have the authorized owner correct the narrow missing permission or configuration only after the target is established. Do not create a duplicate table or broaden credentials merely to remove the symptom.

{"scope":"local resolution review","verify":["resource declaration","package namespace","resolved database and schema","state/defer provenance","runtime principal privileges"]}

Repair the failing layer and preserve the original evidence

Correct YAML scope or macro context where that is the actual cause, then re-evaluate graph and target assumptions separately. For conditional dependencies, use the supported explicit declaration pattern rather than a hardcoded relation name that hides lineage. Verify the generated SQL with the selected dialect through an independently authorized workflow. This guide runs no parse, compile, debug or connection command and grants no permission. Its local checks cover only text structure, dependency reasoning and the review JSON, so no successful dbt compilation or warehouse result is claimed.

Keep it from recurring

• Version engine and adapter assumptions, use logical refs and sources, document macro arguments and file contexts, and retain narrow environment permissions. Include one representative conditional dependency and an undefined-input case in project review fixtures.