Java で「JAVA_HOME is not set」が出てビルドできない

要約

JAVA_HOME を求めるエラーは、ビルドツールが JDK のインストール先を自力で特定できなかったときに出る。java コマンドが動いていても解決しないことがあるのは、実行だけなら JRE で足りるのに対し、コンパイルには javac を含む JDK が要るからである。

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

The JAVA_HOME environment variable is not defined correctly,
this environment variable is needed to run this program.

前者は Gradle の起動スクリプト、後者は Maven の起動スクリプトが出す。
どちらも「JDK の場所を教えてほしい」という同じ要求である。

よくある原因

1. JDK が入っていない: java -version は通るのに javac -version が command not found になる環境は JRE だけの状態である。
   この場合は変数をいくら設定しても直らない。
2. 未設定: Installing Apache Maven（新しいタブで開く）↗ が前提とするとおり、Maven は JAVA_HOME を見て JDK を探す。
   設定していなければそのまま止まる。
3. 指す場所が違う: JAVA_HOME に渡すのは bin の 1 つ上、つまり bin/javac を含むディレクトリである。/usr/lib/jvm/temurin-21/bin のように bin まで含めると bin/bin/javac を探して失敗する。
4. その場限りの export: 端末で export JAVA_HOME=... と打っただけでは、そのシェルを閉じると消える。
   CI やサービス起動では引き継がれない。
5. 古いプロセスが残っている: 環境変数を設定しても、設定前から開いていた IDE やターミナルは古い値を持ち続ける。

解決策

1. JDK があるか確かめる

java -version
javac -version

javac が見つからないなら JDK を入れる。
ディストリビューションのパッケージ（temurin-21-jdk、openjdk-21-jdk など）でよい。

2. JDK のパスを特定する

macOS:

/usr/libexec/java_home -V
export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Linux:

readlink -f $(which javac)
# /usr/lib/jvm/temurin-21-jdk-amd64/bin/javac
export JAVA_HOME=/usr/lib/jvm/temurin-21-jdk-amd64

javac の実体パスから /bin/javac を取り除いたものが JAVA_HOME である。

3. 永続化する

echo 'export JAVA_HOME=/usr/lib/jvm/temurin-21-jdk-amd64' >> ~/.bashrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.bashrc

Windows は PowerShell を管理者権限で開き、システム環境変数に登録する。

[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-21", "Machine")

登録後は端末と IDE を開き直す。

4. Gradle だけで完結させる

プロジェクト単位で JDK を固定したいなら、Build Environment（新しいタブで開く）↗ が説明する gradle.properties を使う。

org.gradle.java.home=/usr/lib/jvm/temurin-21-jdk-amd64

この指定は Gradle にしか効かないので、Maven も併用しているなら JAVA_HOME 側も設定しておく。