dune "Error: Unbound module X" in CI

The compiler reached a module reference it could not resolve. Under dune this usually means the library that provides the module is not listed in the stanza libraries, or the build directory is stale.

What this error means

dune build stops with "Error: Unbound module X" pointing at a .ml file, even though the dependency installed with opam.

dune

File "bin/main.ml", line 3, characters 2-9:
3 |   Lwt.return ()
      ^^^^^^^
Error: Unbound module Lwt

Common causes

The library is not in the dune stanza

The module lives in a library that is installed but not declared in (libraries ...), so dune never puts it in scope.

A stale build directory

A leftover _build from a different set of dependencies makes dune resolve against outdated artifacts.

How to fix it

Add the library to the stanza

Declare the providing library in the executable or library (libraries ...) field.

bin/dune

(executable
 (name main)
 (libraries lwt lwt.unix))

Rebuild clean

Clear _build so dune recompiles against the current dependency set.

Terminal

dune clean
dune build

How to prevent it

List every library a module needs in the dune stanza.
Run dune clean when dependencies change substantially in CI.
Install deps with opam install . --deps-only before building.