Anchor "Compiling ... failed" building the Solana BPF program in CI

anchor build compiles the on-chain program with the Solana toolchain (cargo build-sbf). When the Rust program has an error, that step fails and anchor reports the build did not complete. The Rust error is the real cause.

What this error means

anchor build stops with a Rust compiler error inside programs/, such as a type mismatch or unresolved import, and the SBF build exits non-zero.

Anchor

error[E0432]: unresolved import `anchor_lang::system_program`
  --> programs/vault/src/lib.rs:2:5
   |
2 |     use anchor_lang::system_program;
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^ no `system_program` in the root
error: could not compile `vault` due to previous error

Common causes

A Rust error in the on-chain program

An unresolved import, type mismatch, or borrow error in programs/*/src makes cargo build-sbf fail before producing the program binary.

An anchor-lang version mismatch

The anchor-lang crate version in Cargo.toml differs from the CLI, so an item the code imports does not exist in that crate version.

How to fix it

Fix the reported Rust error

Read the first error[EXXXX] with its file and line inside programs/.
Correct the import, type, or borrow it names.
Re-run anchor build until the program compiles.

Terminal

anchor build

Align anchor-lang with the CLI version

Match the crate version in Cargo.toml to the Anchor CLI so imported items resolve.

programs/vault/Cargo.toml

[dependencies]
anchor-lang = "0.30.1"

How to prevent it

Keep anchor-lang in Cargo.toml aligned with the CLI version.
Build the program locally before pushing.
Pin the Anchor and Solana toolchain versions in CI.