dbt macro not found in package, compilation failed

TL;DR

dbt cannot find the macro because the package is not installed, the dispatch config points at the wrong namespace, or you called it without the package prefix it needs. Run dbt deps and confirm the package landed in dbt_packages, then check how the macro is meant to be called. Most of these are a missing dbt deps after adding the package to packages.yml.

dbt macro not found in package, compilation failed

Use this when

• Compilation fails naming a macro from a package.
• It works on one machine but not another.
• A package was just added or upgraded.

Not for this skill when

• The macro runs but produces wrong SQL. That is a macro bug.
• Your own project's macro is missing. Check the macros directory.

Steps

1. Run dbt deps and verify the package appears in dbt_packages with the expected version. Note the package is actually installed. Verify: installation is confirmed
2. Check how the macro is namespaced: package macros need the package prefix unless dispatched. Note the correct call form. Verify: the call form is known
3. Review dispatch config if your project overrides the macro: a bad dispatch entry hides the package macro. Note dispatch resolves correctly. Verify: dispatch is ruled out
4. Fix the call or the install, then re-run dbt compile. Note compilation succeeds. Verify: the macro resolves
5. Pin the package version in packages.yml so upgrades do not move the macro. Note the version is locked. Verify: the setup is stable

Variant phrasings

dbt macro not found

The shortened search.

dbt dispatch macro package

The dispatch-shaped phrasing.

Compatibility: dbt Core 1.x. Package layout and dispatch behavior are stable; dbt_packages location is configurable.

Why it happens

dbt resolves macros across your project and all installed packages by namespace, and dispatch lets projects override package macros. That flexibility creates three ways to miss: the package was never installed where this run executes, the call uses a namespace the macro does not live under, or a dispatch entry shadows the macro you wanted. CI runners that skip dbt deps are the classic case: everything resolves locally, nothing resolves in CI.

Edge cases / pitfalls

• Private package repos need git credentials at dbt deps time. A 404 from the repo looks like a missing macro downstream.
• Two packages defining the same macro name resolve by search order. Explicit namespaces beat implicit order.
• Upgrading a package can rename or move macros. Read the changelog before bumping versions.
• dbt clean wipes dbt_packages. A clean without a following dbt deps produces exactly this error.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_d9YxXmUCt9pi0FvIqTnLvQ