Maven "mvn: command not found" in CI - Install or PATH Maven
By Kaveh Alemi·Latchkey
The shell could not find the mvn binary. Either Maven is not installed on the runner, or it is installed but its bin directory is not on PATH.
What this error means
The build step fails instantly with mvn: command not found (or mvn: not found) before any Maven output. Nothing about the POM is reached.
shell
+ mvn -B clean verify
/usr/bin/env: bash: line 1: mvn: command not found
##[error]Process completed with exit code 127.
Diagnose it: resolve the effective POM first
Maven merges parent POMs, profiles, and settings before it builds anything. The configuration causing your failure is frequently inherited or activated by a profile that is on locally and off in CI.
Terminal
# the fully resolved configuration Maven will actually use
mvn help:effective-pom | head -60
# which profiles are active here vs on your machine?
mvn help:active-profiles
# full error, offline-safe, no colour codes to confuse the log
mvn -B -e -X <goal> 2>&1 | tail -60
Common causes
Maven not installed on the runner
A minimal base image or container ships a JDK but not Maven. The mvn launcher simply does not exist.
Maven installed but not on PATH
Maven is unpacked somewhere under /opt, but its bin directory was never added to PATH, so the shell cannot resolve mvn.
How to fix it
Use the Maven Wrapper so no global install is needed
Commit the wrapper and call ./mvnw; it downloads the pinned Maven version on demand.
Terminal
mvn -N wrapper:wrapper -Dmaven=3.9.9 # generate mvnw once, commit it
./mvnw -B clean verify # CI uses the wrapper
Install Maven on the runner
Install the package or unpack the distribution and put its bin on PATH.
Prefer the committed Maven Wrapper (./mvnw) so every runner uses the same pinned Maven without a global install or PATH tweak.
Frequently asked questions
What causes Maven "mvn: command not found" in CI?
There are 2 common causes: maven not installed on the runner and maven installed but not on path. A minimal base image or container ships a JDK but not Maven.
How do I fix Maven "mvn: command not found" in CI?
There are 2 fixes depending on which cause you have: use the maven wrapper so no global install is needed and install maven on the runner. Work through them in order, since the first is the most common.
What does Maven "mvn: command not found" in CI actually mean?
The build step fails instantly with mvn: command not found (or mvn: not found) before any Maven output.
How do I stop Maven "mvn: command not found" in CI happening again?
Prefer the committed Maven Wrapper (./mvnw) so every runner uses the same pinned Maven without a global install or PATH tweak.
