opam env not evaluated (dune/ocaml not on PATH) in CI

opam installs tools into the active switch, but their locations only reach PATH after you evaluate the switch environment. Skip eval $(opam env) and the shell finds no dune, or the system ocaml instead of the switch one.

What this error means

A build step fails with "dune: command not found", or ocaml/ocamlfind resolve to the wrong version, even though opam install succeeded earlier.

opam

$ dune build
/home/runner/work/_temp/script.sh: line 1: dune: command not found
Error: Process completed with exit code 127.

Common causes

The switch environment was never applied

Tools live under ~/.opam/<switch>/bin; without eval $(opam env) that directory is not on PATH for the step.

PATH changes do not cross step boundaries

An eval $(opam env) in one step does not persist to the next; each step needs the switch environment applied or run through opam exec.

How to fix it

Evaluate the switch env or use opam exec

Apply the switch environment in the same step, or wrap the command with opam exec.

Terminal

eval $(opam env)
dune build
# or, without eval:
opam exec -- dune build

Let setup-ocaml export the environment

The setup-ocaml action wires the switch env into subsequent steps, so dune and ocaml are on PATH automatically.

.github/workflows/ci.yml

- uses: ocaml/setup-ocaml@v3
  with:
    ocaml-compiler: '5.1'
- run: dune build

How to prevent it

Run eval $(opam env) in each step that uses switch tools, or use opam exec --.
Prefer setup-ocaml, which exports the switch environment for you.
Do not rely on PATH set in a previous step persisting.