Java "JAVA_HOME is not set" in CI - Set and Export JAVA_HOME

A launcher script (Maven, Gradle, or a shell step) needs JAVA_HOME to locate the JDK, and it is unset with no java on PATH. The build cannot find a Java runtime to use.

What this error means

A step fails up front with ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. No build logic runs because no JDK was located.

shell

ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.

Please set the JAVA_HOME variable in your environment to match the
location of your Java installation.

Common causes

No JDK provisioned on the runner

A minimal image has no Java and no JAVA_HOME. The launcher has nothing to point at.

JAVA_HOME not exported to the build step

A JDK is installed but JAVA_HOME was set in a different shell/step and not exported into the environment of the failing step.

How to fix it

Provision a JDK with setup-java

setup-java installs a JDK and sets JAVA_HOME for subsequent steps.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
- run: echo "JAVA_HOME=${JAVA_HOME}" && java -version

Set and export JAVA_HOME in a container

On a bare image, install a JDK and export JAVA_HOME plus PATH.

Terminal

export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH="${JAVA_HOME}/bin:${PATH}"
java -version

How to prevent it

Use setup-java (or a JDK base image) so JAVA_HOME is always set, and assert java -version early in the job.