{"record":{"id":"01addf59fc40359b","repo":"alibaba/arthas","slug":"can-not-find-tools-jar-under-java-home-javahome-01addf","errorCode":null,"errorMessage":"Can not find tools.jar under java home: {javaHome}","messagePattern":"Can not find tools\\.jar under java home: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"boot/src/main/java/com/taobao/arthas/boot/ProcessUtils.java","lineNumber":293,"sourceCode":"        return FOUND_JAVA_HOME;\n    }\n\n    public static void startArthasCore(long targetPid, List<String> attachArgs) {\n        // find java/java.exe, then try to find tools.jar\n        String javaHome = findJavaHome();\n\n        // find java/java.exe\n        File javaPath = findJava(javaHome);\n        if (javaPath == null) {\n            throw new IllegalArgumentException(\n                    \"Can not find java/java.exe executable file under java home: \" + javaHome);\n        }\n\n        File toolsJar = findToolsJar(javaHome);\n\n        if (JavaVersionUtils.isLessThanJava9()) {\n            if (toolsJar == null || !toolsJar.exists()) {\n                throw new IllegalArgumentException(\"Can not find tools.jar under java home: \" + javaHome);\n            }\n        }\n\n        List<String> command = new ArrayList<String>();\n        command.add(javaPath.getAbsolutePath());\n\n        if (toolsJar != null && toolsJar.exists()) {\n            command.add(\"-Xbootclasspath/a:\" + toolsJar.getAbsolutePath());\n        }\n\n        command.addAll(attachArgs);\n        // \"${JAVA_HOME}\"/bin/java \\\n        // ${opts} \\\n        // -jar \"${arthas_lib_dir}/arthas-core.jar\" \\\n        // -pid ${TARGET_PID} \\\n        // -target-ip ${TARGET_IP} \\\n        // -telnet-port ${TELNET_PORT} \\\n        // -http-port ${HTTP_PORT} \\","sourceCodeStart":275,"sourceCodeEnd":311,"githubUrl":"https://github.com/alibaba/arthas/blob/21cf2e9ba52b305290be7223b980ff504bb9cb5b/boot/src/main/java/com/taobao/arthas/boot/ProcessUtils.java#L275-L311","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a full JDK 8 (not a JRE) as JAVA_HOME so lib/tools.jar is present.","Upgrade to Java 9+ where tools.jar is no longer needed (this branch is then skipped).","Point JAVA_HOME at the JDK root, not the nested jre/ folder.","Verify with: ls $JAVA_HOME/lib/tools.jar."],"exampleFix":"# before (Java 8, JRE-only)\nexport JAVA_HOME=/usr/lib/jvm/java-8/jre\njava -jar arthas-boot.jar   # throws: no tools.jar\n\n# after\nexport JAVA_HOME=/usr/lib/jvm/java-8     # full JDK\njava -jar arthas-boot.jar","handlingStrategy":"validation","validationCode":"if (JavaVersionUtils.isLessThanJava9()) {\n    File t = new File(javaHome, \"lib/tools.jar\");\n    if (!t.isFile()) {\n        throw new IllegalStateException(\"Java <9 requires tools.jar under \" + javaHome);\n    }\n}","typeGuard":"static boolean java9OrLater() {\n    return !JavaVersionUtils.isLessThanJava9();\n}","tryCatchPattern":"try {\n    ProcessUtils.startArthasCore(pid, args);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"tools.jar\") && JavaVersionUtils.isLessThanJava9()) {\n        // install full JDK 8 or upgrade to Java 9+\n    } else throw e;\n}","preventionTips":["On Java <= 8 always use a full JDK so lib/tools.jar exists.","Upgrade to Java 9+ to make tools.jar checks a non-issue.","Point JAVA_HOME at the JDK root, not the jre/ subfolder."],"tags":["boot","jdk","tools-jar","java8","environment"],"backgroundTag":null,"analyzedSha":"21cf2e9ba52b305290be7223b980ff504bb9cb5b","analyzedAt":"2026-08-14T00:57:07.243Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}