alibaba/arthas · error · IllegalArgumentException

Can not find tools.jar under java home: {javaHome}

Error message

Can not find tools.jar under java home: {javaHome}

What it means

ProcessUtils.startArthasCore, after locating java, calls findToolsJar(javaHome). On Java versions less than 9 (JavaVersionUtils.isLessThanJava9()), a null or non-existent tools.jar is fatal and throws IllegalArgumentException("Can not find tools.jar under java home: <home>"). On Java 9+ tools.jar is not required, so this check is skipped.

Source

Thrown at boot/src/main/java/com/taobao/arthas/boot/ProcessUtils.java:293

        return FOUND_JAVA_HOME;
    }

    public static void startArthasCore(long targetPid, List<String> attachArgs) {
        // find java/java.exe, then try to find tools.jar
        String javaHome = findJavaHome();

        // find java/java.exe
        File javaPath = findJava(javaHome);
        if (javaPath == null) {
            throw new IllegalArgumentException(
                    "Can not find java/java.exe executable file under java home: " + javaHome);
        }

        File toolsJar = findToolsJar(javaHome);

        if (JavaVersionUtils.isLessThanJava9()) {
            if (toolsJar == null || !toolsJar.exists()) {
                throw new IllegalArgumentException("Can not find tools.jar under java home: " + javaHome);
            }
        }

        List<String> command = new ArrayList<String>();
        command.add(javaPath.getAbsolutePath());

        if (toolsJar != null && toolsJar.exists()) {
            command.add("-Xbootclasspath/a:" + toolsJar.getAbsolutePath());
        }

        command.addAll(attachArgs);
        // "${JAVA_HOME}"/bin/java \
        // ${opts} \
        // -jar "${arthas_lib_dir}/arthas-core.jar" \
        // -pid ${TARGET_PID} \
        // -target-ip ${TARGET_IP} \
        // -telnet-port ${TELNET_PORT} \
        // -http-port ${HTTP_PORT} \

View on GitHub (pinned to 21cf2e9ba5)

Solutions

  1. Use a full JDK 8 (not a JRE) as JAVA_HOME so lib/tools.jar is present.
  2. Upgrade to Java 9+ where tools.jar is no longer needed (this branch is then skipped).
  3. Point JAVA_HOME at the JDK root, not the nested jre/ folder.
  4. Verify with: ls $JAVA_HOME/lib/tools.jar.

Example fix

# before (Java 8, JRE-only)
export JAVA_HOME=/usr/lib/jvm/java-8/jre
java -jar arthas-boot.jar   # throws: no tools.jar

# after
export JAVA_HOME=/usr/lib/jvm/java-8     # full JDK
java -jar arthas-boot.jar
Defensive patterns

Strategy: validation

Validate before calling

if (JavaVersionUtils.isLessThanJava9()) {
    File t = new File(javaHome, "lib/tools.jar");
    if (!t.isFile()) {
        throw new IllegalStateException("Java <9 requires tools.jar under " + javaHome);
    }
}

Type guard

static boolean java9OrLater() {
    return !JavaVersionUtils.isLessThanJava9();
}

Try / catch

try {
    ProcessUtils.startArthasCore(pid, args);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("tools.jar") && JavaVersionUtils.isLessThanJava9()) {
        // install full JDK 8 or upgrade to Java 9+
    } else throw e;
}

Prevention

When it happens

Trigger: Running arthas-boot on Java 8 (or earlier) where findToolsJar returns null or a non-existent file — i.e. the JDK layout lacks lib/tools.jar and the ../lib and ../../lib fallbacks.

Common situations: JRE-only install used as JAVA_HOME on Java 8; custom/trimmed JDK image without tools.jar; JAVA_HOME pointing at a nested jre directory that defeats the fallback resolution.

Related errors

AI-assisted analysis of alibaba/arthas@21cf2e9ba5 (2026-08-14). Data as JSON: /api/errors/01addf59fc40359b. Report an issue: GitHub.