alibaba/arthas · critical · IllegalStateException

can not find arthas-core.jar under arthasHome: ${arthasHome}

Error message

can not find arthas-core.jar under arthasHome: ${arthasHome}

What it means

Thrown when arthasHome was resolved (explicitly or by extracting arthas-bin.zip) but the expected arthas-core.jar is missing under that directory. ArthasAgent needs arthas-core.jar to load ArthasBootstrap via a dedicated classloader.

Source

Thrown at arthas-agent-attach/src/main/java/com/taobao/arthas/agent/attach/ArthasAgent.java:110

            // 检查 arthasHome
            if (arthasHome == null || arthasHome.trim().isEmpty()) {
                // 解压出 arthasHome
                URL coreJarUrl = this.getClass().getClassLoader().getResource("arthas-bin.zip");
                if (coreJarUrl != null) {
                    File tempArthasDir = createTempDir();
                    ZipUtil.unpack(coreJarUrl.openStream(), tempArthasDir);
                    arthasHome = tempArthasDir.getAbsolutePath();
                } else {
                    throw new IllegalArgumentException("can not getResources arthas-bin.zip from classloader: "
                            + this.getClass().getClassLoader());
                }
            }

            // find arthas-core.jar
            File arthasCoreJarFile = new File(arthasHome, ARTHAS_CORE_JAR);
            if (!arthasCoreJarFile.exists()) {
                throw new IllegalStateException("can not find arthas-core.jar under arthasHome: " + arthasHome);
            }
            AttachArthasClassloader arthasClassLoader = new AttachArthasClassloader(
                    new URL[] { arthasCoreJarFile.toURI().toURL() });

            /**
             * <pre>
             * ArthasBootstrap bootstrap = ArthasBootstrap.getInstance(inst);
             * </pre>
             */
            Class<?> bootstrapClass = arthasClassLoader.loadClass(ARTHAS_BOOTSTRAP);
            Object bootstrap = bootstrapClass.getMethod(GET_INSTANCE, Instrumentation.class, Map.class).invoke(null,
                    instrumentation, configMap);
            boolean isBind = (Boolean) bootstrapClass.getMethod(IS_BIND).invoke(bootstrap);
            if (!isBind) {
                String errorMsg = "Arthas server port binding failed! Please check $HOME/logs/arthas/arthas.log for more details.";
                throw new RuntimeException(errorMsg);
            }
        } catch (Throwable e) {

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Verify arthas-core.jar exists under the configured arthasHome (ls $arthasHome/arthas-core.jar).
2. Reinstall/refresh the arthas distribution so the directory is complete.
3. Point arthasHome at the correct root directory that contains arthas-core.jar.

Example fix

// before
config.put("arthasHome", "/opt/arthas/lib"); // no arthas-core.jar here

// after
config.put("arthasHome", "/opt/arthas"); // contains arthas-core.jar

java.io.File core = new java.io.File(arthasHome, "arthas-core.jar");
if (!core.exists()) throw new IllegalStateException("arthas-core.jar missing under " + arthasHome);

When it happens

Trigger: arthasHome points at a partial/incomplete arthas installation; an extracted arthas-bin.zip that lacked arthas-core.jar; a typo or wrong path in the arthasHome config.

Common situations: Manually copying only some arthas jars; an interrupted unzip; pointing arthasHome at the lib subdir instead of the install root.

Related errors

• File '{}' exists but is a directory
• can not getResources arthas-bin.zip from classloader: ${clas
• Arthas server port binding failed! Please check $HOME/logs/a
• Failed to create directory within ${TEMP_DIR_ATTEMPTS} attem
• ${name}: Is a directory

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