Rust Incremental Compilation Cache Corruption in CI

rustc tripped over a corrupted incremental-compilation or target cache - typically a partially restored CI cache, a toolchain change against stale artifacts, or an interrupted prior build. The fix is to clear the cache and rebuild clean; it’s mechanical, not a source bug.

What this error means

The build fails with found invalid metadata files, failed to read ... incremental, or an ICE referencing the incremental/target directory. It often follows a restored cache or a toolchain bump, and a clean rebuild succeeds with no code change - the mark of cache corruption rather than a real error.

cargo output

error: failed to write dep-info to ... target/debug/incremental/...
thread 'rustc' panicked at 'found invalid metadata files for crate `app`'
error: internal compiler error: unexpected panic
note: the compiler unexpectedly panicked. this is a bug.

Common causes

Partially restored or mismatched cache

A CI cache restored over a different toolchain, or an incomplete restore, leaves incremental metadata inconsistent with the current compiler, which rustc rejects.

Interrupted or OOM-killed prior build

A previous build that was cancelled or OOM-killed mid-write can leave half-written artifacts in target/incremental, poisoning the next build.

How to fix it

Clear the cache and rebuild

Remove the corrupted incremental/target artifacts so the next build regenerates them cleanly.

Terminal

cargo clean
# or just the incremental dirs:
rm -rf target/debug/incremental target/release/incremental
cargo build --locked

Key the CI cache on the toolchain and disable incremental in CI

Include the rustc version in the cache key, and turn off incremental in CI where it mostly adds risk over a clean build.

.github/workflows/ci.yml

# avoid incremental in CI
export CARGO_INCREMENTAL=0
# cache key includes the toolchain:
# key: cargo-${{ steps.toolchain.outputs.version }}-${{ hashFiles('Cargo.lock') }}

How to prevent it

Set CARGO_INCREMENTAL=0 in CI to avoid incremental cache hazards.
Include the rustc/toolchain version in the cargo cache key.
Bust the cache when the toolchain changes rather than restoring stale artifacts.