What causes DbtMacroNotFoundError?

A macro from a package (e.g., dbt_utils.generate_surrogate_key) is called but dbt deps was not run after the package was added. The macro name contains a typo or incorrect namespace prefix. The macro file was deleted or moved without updating all references in models and schema.yml. A macro was renamed in a package version upgrade but model references were not updated

How do I fix DbtMacroNotFoundError?

Step 1: Run dbt deps to install or update all packages listed in packages.yml.. Step 2: Verify the macro name and namespace — package macros use the format . .. Step 3: Search the project macros/ directory and installed dbt_packages/ for the exact macro name.. Step 4: If the macro was renamed in a package upgrade, update all references in models and configuration files.. Step 5: Run dbt compile after the fix to confirm the macro resolves before running the full pipeline.

High severitycompilation

Power BI Refresh Error:
DbtMacroNotFoundError

What does this error mean?

dbt cannot find a macro referenced in a model, test, or hook — either because the macro does not exist in the project or its packages, or dbt deps has not been run after adding a package.

Common causes

1A macro from a package (e.g., dbt_utils.generate_surrogate_key) is called but dbt deps was not run after the package was added
2The macro name contains a typo or incorrect namespace prefix
3The macro file was deleted or moved without updating all references in models and schema.yml
4A macro was renamed in a package version upgrade but model references were not updated

How to fix it

1Step 1: Run dbt deps to install or update all packages listed in packages.yml.
2Step 2: Verify the macro name and namespace — package macros use the format <package_name>.<macro_name>.
3Step 3: Search the project macros/ directory and installed dbt_packages/ for the exact macro name.
4Step 4: If the macro was renamed in a package upgrade, update all references in models and configuration files.
5Step 5: Run dbt compile after the fix to confirm the macro resolves before running the full pipeline.

Frequently asked questions

Why do I get 'macro is undefined' even though it is in packages.yml?

Running dbt deps is required to download and install packages. Simply listing a package in packages.yml does not make it available — you must run dbt deps, especially after adding a new package or modifying version constraints.

Can I define project-level macros that override package macros?

Yes — dbt uses a dispatch order for macros. Project macros take precedence over package macros with the same name. Use this feature to customize package macro behavior without forking the package.