Java "Could not find tools.jar" in CI - Use a JDK, Not a JRE

By Daniel Zoghalchali·Latchkey

tools.jar shipped inside the JDK (not the JRE) through Java 8 and held the compiler/javadoc APIs. A build fails to find it when JAVA_HOME is a JRE, or when an old tool looks for it on JDK 9+ where it no longer exists.

What this error means

A plugin (older AspectJ, GWT, some annotation processors, javadoc tooling) fails with Could not find tools.jar. Please check that ${JAVA_HOME}/lib/tools.jar exists. JAVA_HOME is a JRE, or the tool assumes a pre-9 JDK layout.

maven

[ERROR] Failed to execute goal ... : Could not find tools.jar.
Please check that ${env.JAVA_HOME}/lib/tools.jar exists. JAVA_HOME =
/usr/lib/jvm/java-8-jre

Common causes

JAVA_HOME points at a JRE

A JRE has no lib/tools.jar. Tools that compile/process annotations through that jar cannot start until JAVA_HOME is a full JDK.

tools.jar removed on JDK 9+

From Java 9 the compiler APIs moved into modules and tools.jar was deleted. An old tool that still expects the file fails on a modern JDK.

How to fix it

Point JAVA_HOME at a full JDK 8 for legacy tools

If the tool needs tools.jar, run it under a JDK 8 that still ships it.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '8'
- run: test -f "${JAVA_HOME}/lib/tools.jar" && mvn -B verify

Or upgrade the tool to a JDK 9+ compatible version

Update the plugin/library to a release that uses the module compiler APIs instead of tools.jar.
Confirm JAVA_HOME is a JDK (has bin/javac), never a JRE.
Remove any hardcoded lib/tools.jar references from the build.

How to prevent it

Run builds on a full JDK and keep tooling current so it does not depend on the removed tools.jar layout.

Frequently asked questions

What causes ""Could not find tools.jar""?

A JRE has no lib/tools.jar. Tools that compile/process annotations through that jar cannot start until JAVA_HOME is a full JDK.

How do I fix "Could not find tools.jar"?