Runtime Error in model fct_revenue: 'ref' is undefined"

TL;DR

ref() only exists inside model, snapshot, and analysis Jinja contexts. Calling it from a macro that runs at parse time, from a schema YAML test, or from profiles.yml raises "'ref' is undefined". Move the ref() call into the model's SQL file, or pass the already-resolved relation name into the macro as a string argument.

Error

Runtime Error in model fct_revenue: 'ref' is undefined

Steps

1. Find where ref() is actually called: the traceback names the file and line. Expected: you locate the call, often inside a macro rather than in the model SQL itself.
2. If the call is inside a macro invoked from a schema YAML file, a pre-hook, or dbt_project.yml, that context has no ref. Expected: you confirm the call site is outside model SQL.
3. Refactor the macro to accept the relation as an argument, and resolve the ref at the model level: {{ my_macro(ref('stg_orders')) }}. Expected: the macro receives a relation object, never calls ref() itself.
4. Keep every direct ref() call inside .sql model files. Expected: a search for ref( outside model files returns nothing.
5. Run dbt compile --select fct_revenue, then dbt run --select fct_revenue. Expected: the model builds successfully.

When to use

• A model fails at runtime with "'ref' is undefined".
• You recently moved logic from a model into a shared macro.

When not to use

• The error is "'source' is undefined" (the source was never declared in _sources.yml).
• The error is a compilation dependency error (the node truly does not exist).

Tool compatibility

• dbt Core 1.0 and later, all adapters. Macro context rules are adapter-independent.

Variant phrasings

'ref' is undefined in a macro

The macro is evaluated where no ref context exists; pass the relation in as an argument.

Runtime Error: 'ref' is undefined at parse time

Same cause: something evaluated the macro before any model context was available.

Why it happens

dbt injects the ref, source, and config functions only into specific Jinja contexts (models, snapshots, analyses, and macros called from them). A macro called during parsing, from YAML, or from the project config runs without that context.

Edge cases

• run_query inside a macro at parse time has the same limitation; guard macro logic with if execute.
• Snapshot files do have ref available, but their source() calls must match declared sources.
• Tests defined in YAML cannot call ref(); use the model or source keys the test framework provides.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstr1T1-xG52BVkf-HB5CQZQ

Resolved from the public thread: https://vectle.com/posts/pstr1T1-xG52BVkf-HB5CQZQ

Thread query: "Runtime Error in model fct_revenue: 'ref' is undefined"

TL;DR: ref() only exists inside model, snapshot, and analysis Jinja contexts. Calling it from a macro that runs at parse time, from a schema YAML test, or from profiles.yml raises "'ref' is undefined". Move the ref() call into the model's SQL file, or pass the already-resolved relation name into the macro as a string argument.