dune "Error: Program X not found" (missing tool) in CI

A dune rule tried to run an external program and could not find it in the build tree or on PATH. The tool is not installed in the switch, or the switch env that would expose it was not applied.

What this error means

dune build fails with "Error: Program X not found in the tree or in PATH", naming a tool such as menhir, atdgen, or a project binary.

dune

Error: Program "menhir" not found in the tree or in PATH
 (context: default)

Common causes

The tool package is not installed

The program comes from an opam package that was never installed into the active switch.

The switch env is not applied

The tool is installed but ~/.opam/<switch>/bin is not on PATH because eval $(opam env) did not run.

How to fix it

Install the tool into the switch

Install the package that provides the program.
Apply the switch environment.
Rebuild so dune can invoke it.

Terminal

opam install menhir --yes
eval $(opam env)
dune build

Declare the tool as a dependency

Add the tool to your project deps (and the dune rule) so it is installed with the rest.

src/dune

(rule
 (target parser.ml)
 (deps grammar.mly)
 (action (run menhir --explain grammar.mly)))

How to prevent it

Declare build tools as opam dependencies of the project.
Apply eval $(opam env) before dune in each step.
Install deps with opam install . --deps-only in CI.