Introduction

On Ubuntu, Java tools such as Maven, Gradle, and application servers often depend on a correct JAVA_HOME value and a working PATH. If those variables point to the wrong location, builds fail or use the wrong JDK version without obvious errors. A reliable setup includes discovery, configuration, and verification steps.

Find Installed JDK Paths

Start by confirming Java is installed and listing available JDK directories. Ubuntu commonly stores JDK installations under /usr/lib/jvm.

java -version
javac -version
ls -1 /usr/lib/jvm

If Java is missing, install a JDK first:

sudo apt update
sudo apt install -y openjdk-17-jdk

After installation, check the path of the active java binary:

readlink -f "$(command -v java)"

The output usually points to a path such as /usr/lib/jvm/java-17-openjdk-amd64/bin/java. The parent directory ending in /bin is useful for PATH; the directory one level above is your JAVA_HOME.

Set JAVA_HOME for One User Session

For per user shell configuration, add exports to ~/.bashrc or ~/.zshrc depending on your shell. This is the safest first step because it does not change settings for all users.

1# Example for Bash
2cat >> ~/.bashrc <<'BASH_EOF'
3export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
4export PATH="$JAVA_HOME/bin:$PATH"
5BASH_EOF
6
7source ~/.bashrc

Verify:

echo "$JAVA_HOME"
java -version
javac -version

If the printed path and versions match your target JDK, shell setup is working.

Configure System Wide Java Environment

For server environments, use a profile script in /etc/profile.d so all interactive users load the same defaults.

1sudo tee /etc/profile.d/java.sh >/dev/null <<'EOF2'
2export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
3export PATH="$JAVA_HOME/bin:$PATH"
4EOF2
5
6sudo chmod 644 /etc/profile.d/java.sh

Open a new session and validate again with echo "$JAVA_HOME" and java -version.

For non interactive services managed by systemd, put environment values in the service unit or an environment file instead of relying on shell startup files.

Manage Multiple JDKs with update-alternatives

Ubuntu can install several JDK versions. Use update-alternatives to choose default binaries for commands like java and javac.

sudo update-alternatives --config java
sudo update-alternatives --config javac

These commands show numbered choices. Select the desired path, then recheck:

java -version
javac -version

Even when alternatives are set, keep JAVA_HOME aligned with the same JDK to avoid mixed runtime and compiler versions.

Example Verification Script

A short validation script is useful for onboarding and CI environment checks.

1#!/usr/bin/env bash
2set -euo pipefail
3
4echo "JAVA_HOME=$JAVA_HOME"
5which java
6which javac
7java -version
8javac -version

Save as check-java-env.sh, run with bash check-java-env.sh, and keep it in your repository documentation.

Troubleshoot Version Mismatch in Build Tools

Sometimes java -version is correct, but Gradle or Maven still reports another JDK. This usually means one tool has a local override. Check Gradle and Maven output, then inspect environment variables inside the same shell where you run the build.

./gradlew -version
mvn -version
env | grep -E '^JAVA_HOME|^PATH'

If a CI runner still uses the wrong Java version, print these values at the start of your job and compare with local output. Keep the verification logs in pull requests when changing JDK versions so reviewers can confirm the migration is complete.

Common Pitfalls

• Setting JAVA_HOME to the binary path ending with java. It should point to the JDK home directory, not the executable file.
• Updating .bashrc and expecting service processes to inherit it. Services usually need explicit environment settings.
• Mixing JDK versions between java and javac. Verify both commands after every change.
• Forgetting to open a new shell after editing profile files. Old sessions keep old environment values.
• Using relative paths in exports. Prefer absolute paths under /usr/lib/jvm for consistency.

Summary

• Install and verify JDK packages before setting environment variables.
• Set JAVA_HOME and prepend JAVA_HOME/bin to PATH in the correct shell file.
• Use /etc/profile.d for shared server defaults.
• Use update-alternatives when multiple JDK versions are installed.
• Validate with command outputs so tooling and builds use the intended Java version.