ccache "Could not find compiler" / masquerading symlink in CI

ccache is invoked under the compiler's own name (a masquerading symlink like /usr/lib/ccache/gcc) but cannot locate the real compiler behind it, so it has nothing to run and no result to cache.

What this error means

The build stops with "ccache: error: Could not find compiler \"gcc\" in PATH" or "Recursive invocation", typically when /usr/lib/ccache is on PATH ahead of the real toolchain.

ccache: error: Could not find compiler "gcc" in PATH

Common causes

The masquerade dir shadows the real compiler

/usr/lib/ccache contains gcc/g++ symlinks to ccache. If that directory is on PATH but the real gcc is not, ccache cannot find the compiler to delegate to.

A launcher that points ccache at ccache

Setting CC to a ccache symlink while also using ccache as launcher can create a loop where ccache resolves to itself instead of a compiler.

How to fix it

Use the launcher form, not the symlink shadow

1. Prefer CC="ccache gcc" or CMake's compiler-launcher over the /usr/lib/ccache PATH trick.
2. Ensure the real gcc/clang stays on PATH behind the masquerade dir.
3. Re-run so ccache finds and delegates to the real compiler.

export CC="ccache gcc"
export CXX="ccache g++"
cmake -S . -B build

Set the compiler launcher in CMake

Let CMake wrap the resolved compiler so the real binary is always known and no symlink loop forms.

cmake -S . -B build \
  -DCMAKE_C_COMPILER_LAUNCHER=ccache \
  -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

How to prevent it

• Prefer the compiler-launcher form over the /usr/lib/ccache PATH masquerade.
• Keep the real gcc/clang on PATH behind any masquerade directory.
• Never point ccache at a ccache symlink as its compiler.

Related guides