dune "Error: Unbound module" in CI

By Kaveh Alemi·Latchkey

The OCaml compiler reached a module name that is not visible from the current compilation unit. Under dune this almost always means the library that provides it is missing from the stanza's libraries field.

What this error means

dune build fails with "Error: Unbound module X" pointing at a file that uses a module from a library not listed in its dune stanza.

File "bin/main.ml", line 1, characters 0-12:
1 | let () = Lwt_main.run (main ())
    ^^^^^^^^^^^^
Error: Unbound module Lwt_main

Common causes

The library is not in the dune stanza

The module belongs to a package (here lwt) that is not listed in (libraries ...), so dune does not put it on the compile path.

A wrapped library hides the module name

A wrapped library exposes its modules under a top-level name; referencing an inner module directly fails unless you go through the wrapper.

How to fix it

Add the library to the stanza

1. Find which package provides the module (for example lwt.unix for Lwt_main).
2. Add it to (libraries ...) in the matching dune file.
3. Re-run dune build to confirm the module resolves.

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

Reference modules through the wrapper

For a wrapped library, access the module via its library namespace rather than the bare inner name.

How to prevent it

• Keep (libraries ...) in sync with the modules each unit actually uses.
• Install dependencies with opam before dune build in CI.
• Build locally so unbound-module errors surface before pushing.

Frequently asked questions

Related guides

References

• GitHub Actions documentation