alibaba/arthas · error · IllegalArgumentException

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

Error message

Can not find tools.jar under java home: {javaHome}, please try to start arthas-boot with full path java. Such as /opt/jdk/bin/java -jar arthas-boot.jar

What it means

ProcessUtils.findJavaHome (the JAVA_HOME-env branch, ~line 269) searches for tools.jar relative to the JAVA_HOME environment variable. If neither $JAVA_HOME/lib/tools.jar nor $JAVA_HOME/../lib/tools.jar exists, it throws IllegalArgumentException instructing the user to start arthas-boot with a full JDK java path. This branch matters only for JDK 8 and earlier where tools.jar is required.

Source

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

                AnsiLog.debug("Can not find tools.jar under java.home: " + javaHome);
                String javaHomeEnv = System.getenv("JAVA_HOME");
                if (javaHomeEnv != null && !javaHomeEnv.isEmpty()) {
                    AnsiLog.debug("Try to find tools.jar in System Env JAVA_HOME: " + javaHomeEnv);
                    // $JAVA_HOME/lib/tools.jar
                    toolsJar = new File(javaHomeEnv, "lib/tools.jar");
                    if (!toolsJar.exists()) {
                        // maybe jre
                        toolsJar = new File(javaHomeEnv, "../lib/tools.jar");
                    }
                }

                if (toolsJar.exists()) {
                    AnsiLog.info("Found java home from System Env JAVA_HOME: " + javaHomeEnv);
                    FOUND_JAVA_HOME = javaHomeEnv;
                    return FOUND_JAVA_HOME;
                }

                throw new IllegalArgumentException("Can not find tools.jar under java home: " + javaHome
                        + ", please try to start arthas-boot with full path java. Such as /opt/jdk/bin/java -jar arthas-boot.jar");
            }
        } else {
            FOUND_JAVA_HOME = javaHome;
        }
        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);
        }

View on GitHub (pinned to 21cf2e9ba5)

Solutions

Install a full JDK (not JRE) and set JAVA_HOME to the JDK root.
Start arthas-boot with an explicit full JDK path: /opt/jdk/bin/java -jar arthas-boot.jar.
Verify tools.jar exists at $JAVA_HOME/lib/tools.jar.
On Java 9+ tools.jar no longer exists — ensure you are not forcing an older detection path.

Example fix

# before
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/jre   # JRE: no tools.jar
java -jar arthas-boot.jar

# after
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64       # JDK root
/opt/jdk/bin/java -jar arthas-boot.jar

Defensive patterns

Strategy: validation

Validate before calling

String jh = System.getenv("JAVA_HOME");
File tools = new File(jh, "lib/tools.jar");
if (!tools.isFile() && !new File(jh, "../lib/tools.jar").isFile()) {
    throw new IllegalStateException("JAVA_HOME lacks tools.jar; use a full JDK");
}

Type guard

static boolean hasToolsJar(String javaHome) {
    if (javaHome == null) return false;
    return new File(javaHome, "lib/tools.jar").isFile()
        || new File(javaHome, "../lib/tools.jar").isFile();
}

Try / catch

try {
    ProcessUtils.findJavaHome();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("tools.jar")) {
        // switch JAVA_HOME to a JDK, or use full-path java
    } else throw e;
}

Prevention

Install a full JDK (not JRE) for Java <= 8 work.
Set JAVA_HOME to the JDK root and verify lib/tools.jar exists.
Launch with /opt/jdk/bin/java -jar arthas-boot.jar when in doubt.

When it happens

Trigger: Running on Java <= 8 with JAVA_HOME pointing at a JRE (not a JDK), or JAVA_HOME unset/misconfigured so that tools.jar cannot be located relative to it.

Common situations: Container image ships a JRE only; JAVA_HOME points at /usr/lib/jvm/.../jre instead of the JDK root; system 'java' is a JRE stub; downstream of a version-detection path that picked the wrong home.

Related errors

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