JAVA_HOME

Why do java and Maven disagree about my Java version?

Because they resolve the JDK through two unrelated mechanisms. java on the command line is found via PATH — first matching binary wins. Maven's mvn launcher script explicitly uses $JAVA_HOME/bin/java when JAVA_HOME is set. Install a new JDK that updates one but not the other and you get the canonical confusion:

$ java -version        # resolved via PATH
openjdk version "21.0.3"

$ mvn -version          # resolved via JAVA_HOME
Apache Maven 3.9.6
Java version: 17.0.10, vendor: Eclipse Adoptium

The fix is to derive both from the same root, in this order, in your shell profile:

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

What reads JAVA_HOME — and what doesn't

• Reads it: Maven (hard requirement — the launcher errors with "JAVA_HOME should point to a JDK, not a JRE" when misconfigured), Gradle (picks the JVM that runs the build unless org.gradle.java.home overrides it), Tomcat's catalina.sh (JRE_HOME takes precedence if both are set), Jenkins agents, Android tooling, and most IDE launcher scripts.
• Ignores it: the java and javac binaries themselves. JAVA_HOME is a convention consumed by the tooling layer, never by the JVM launcher — which is exactly why the two can disagree.

Gradle has been quietly reducing JAVA_HOME's importance: toolchains (Gradle 6.7+) let the build declare "I need Java 17" and auto-provision a matching JDK, so the JVM compiling your code may be neither the PATH one nor the JAVA_HOME one. When debugging a Gradle build, trust gradle -version and the toolchain report over any environment variable.

Setting it per OS without hardcoding paths

# macOS — never hardcode /Library/Java/...; ask the resolver:
export JAVA_HOME=$(/usr/libexec/java_home -v 21)

# Debian/Ubuntu — list candidates, then pin:
update-java-alternatives --list
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

# Anywhere — let a version manager own it:
sdk use java 21.0.3-tem   # SDKMAN! exports JAVA_HOME for you

On Windows, JDK installers (Adoptium's MSI has an explicit "Set JAVA_HOME" checkbox) write it to the system environment. Two Windows-specific traps: don't include quotes in the value itself — scripts that expand %JAVA_HOME%\bin end up with quotes mid-path — and after editing System Properties, only newly opened terminals see the change.

JDK root, not bin — the off-by-one-directory bug

Every consumer of JAVA_HOME appends paths like /bin/java or /lib/tools.jar to it. Point it at .../jdk-21/bin and tools look for .../jdk-21/bin/bin/java; point it at the binary itself and they look for .../java/bin/java. The quick self-check is one line: "$JAVA_HOME/bin/java" -version — if that fails, every downstream tool will too. In Docker images the equivalent is checking the base image's convention first: the official eclipse-temurin images already set JAVA_HOME and PATH correctly, so re-setting them in your Dockerfile is usually copy-paste cargo culting. How ENV layering works there is covered in the Docker environment variables guide.

Reading config from Java itself

Inside the JVM, System.getenv("JAVA_HOME") returns whatever the process inherited — but the honest source of truth for "which Java am I running" is the system property System.getProperty("java.home"), which the JVM computes from its own install location and which cannot lie. The broader pattern of environment variables vs system properties in Java — including why -D flags and env vars get confused — is the subject of the Java environment variables guide.