dbt "Compilation Error: macro not found" in CI

dbt compiled a model and encountered a macro call it cannot resolve. The macro is either misspelled, defined in a package that was not installed, or not on the macro paths dbt searches.

What this error means

dbt compile or run fails with "Compilation Error ... 'X' is undefined" or a message that the macro could not be found, pointing at the calling model.

dbt

Compilation Error in model stg_orders (models/staging/stg_orders.sql)
  'dbt_utils' is undefined. This can happen when calling a macro that does
  not exist. Check for typos and/or install package dependencies with "dbt deps".

Common causes

A package macro used before dbt deps ran

The model calls a macro namespaced to a package (dbt_utils) that was not installed, so the namespace is undefined.

A typo in the macro name

The macro string does not match any defined macro, so dbt reports it as undefined at compile time.

How to fix it

Install packages before compiling

Add the package to packages.yml.
Run dbt deps so the macro namespace is available.
Run dbt compile to confirm the macro resolves.

Terminal

dbt deps
dbt compile

Declare the package dependency

List the package that provides the macro so dbt deps installs it in CI.

packages.yml

packages:
  - package: dbt-labs/dbt_utils
    version: 1.1.1

How to prevent it

Run dbt deps before compile in every CI job.
Reference macros by the exact package namespace and name.
Pin package versions in packages.yml so macros stay available.