dune "Files ... have inconsistent assumptions" (.cmi) in CI

The linker found two compiled units built against different versions of the same interface (.cmi). This is almost always a stale _build or a mismatched dependency; a clean build fixes it.

What this error means

dune build or link fails with "Error: Files A.cmx and B.cmx make inconsistent assumptions over interface X", typically after switching branches or upgrading a dependency.

dune

Error: Files bin/main.cmx and lib/util.cmx
make inconsistent assumptions over interface Util

Common causes

Stale artifacts in the build directory

A leftover _build holds .cmi/.cmx files compiled against an older interface than the current sources.

A dependency recompiled against a different interface

An upgraded or repinned library exposes a changed interface, so previously compiled units no longer agree.

How to fix it

Build clean

Remove _build so every unit recompiles against the current interfaces.

Terminal

dune clean
dune build

Do not cache _build across incompatible changes

If CI caches _build, key the cache on the lockfile and compiler so it invalidates when interfaces change.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: _build
    key: dune-${{ hashFiles('**/*.opam','dune-project') }}

How to prevent it

Run dune clean in CI when dependencies or the compiler change.
Key any _build cache on the lockfile and compiler version.
Avoid reusing a build directory across incompatible branches.