How to Fix 'ref not found' Error in dbt Quickly

The ref not found error in dbt happens when you use ref() to call a model that dbt cannot find. To fix it, ensure the referenced model exists in your project and is spelled correctly in the ref() call.

Why This Happens

This error occurs because dbt tries to find a model you referenced with ref(), but it does not exist or is misspelled. It can also happen if the model is in a different directory or package and not properly referenced.

jinja

select * from {{ ref('my_model') }}

Output

Compilation Error in model my_model.sql
  'my_model' not found in project

The Fix

Check that the model name inside ref() exactly matches the model file name without the extension. Also, confirm the model file exists in your models/ folder or the correct package if using multiple packages.

jinja

select * from {{ ref('correct_model_name') }}

Output

Compiled SQL runs successfully and returns data from the referenced model

Prevention

To avoid this error, always use autocomplete or copy-paste model names when using ref(). Keep your project organized and run dbt ls to list available models. Use consistent naming conventions and check your dbt_project.yml for correct model paths.

Related Errors

Other common errors include:

• Model not found in package: Happens when referencing models from other packages without proper package name prefix.
• Circular dependencies: When two models reference each other causing build errors.
• Compilation errors: Syntax issues inside model SQL causing failure.

Key Takeaways

Always verify the model name inside ref() matches an existing model file.

Use dbt commands like dbt ls to check available models before referencing.

Keep your project structure clear and consistent to avoid missing references.

Use autocomplete or copy-paste to reduce typos in ref() calls.

Check package names when referencing models across packages.