alibaba/arthas · error · IllegalArgumentException

illegal arthas home: {arthasHome}

Error message

illegal arthas home: {arthasHome}

What it means

Bootstrap.verifyArthasHome throws IllegalArgumentException("illegal arthas home: <path>") when the supplied arthasHome does not resolve to a directory at all (File.isDirectory() is false) — i.e. it is a file, or it does not exist. This is the fallback reached before the per-jar checks run.

Source

Thrown at boot/src/main/java/com/taobao/arthas/boot/Bootstrap.java:759

        }
        return names;
    }

    private static void verifyArthasHome(String arthasHome) {
        File home = new File(arthasHome);
        if (home.isDirectory()) {
            String[] fileList = { "arthas-core.jar", "arthas-agent.jar", "arthas-spy.jar" };

            for (String fileName : fileList) {
                if (!new File(home, fileName).exists()) {
                    throw new IllegalArgumentException(
                                    fileName + " do not exist, arthas home: " + home.getAbsolutePath());
                }
            }
            return;
        }

        throw new IllegalArgumentException("illegal arthas home: " + home.getAbsolutePath());
    }

    private static String usage(CLI cli) {
        StringBuilder usageStringBuilder = new StringBuilder();
        UsageMessageFormatter usageMessageFormatter = new UsageMessageFormatter();
        usageMessageFormatter.setOptionComparator(null);
        cli.usage(usageStringBuilder, usageMessageFormatter);
        return UsageRender.render(usageStringBuilder.toString());
    }

    public String getArthasHome() {
        return arthasHome;
    }

    public String getUseVersion() {
        return useVersion;
    }

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Confirm the path exists and is a directory (ls -ld <path>).
2. Use an absolute path for --arthas-home to avoid working-directory ambiguity.
3. Extract the distribution archive fully before pointing at it.
4. Reinstall Arthas to a known-good directory.

Example fix

# before
java -jar arthas-boot.jar --arthas-home ./arthas-bin.zip

# after
unzip arthas-bin.zip -d /opt/arthas
java -jar arthas-boot.jar --arthas-home /opt/arthas

File home = new File(arthasHome);
if (!home.isDirectory()) {
    throw new IllegalStateException("not a directory: " + home);
}

static boolean isDirectoryHome(String path) {
    return path != null && new File(path).isDirectory();
}

try {
    Bootstrap.verifyArthasHome(home);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("illegal arthas home")) {
        // repoint to a real directory
    } else throw e;
}

When it happens

Trigger: Thrown at boot/src/main/java/com/taobao/arthas/boot/Bootstrap.java:759 when the library encounters an invalid state.

Common situations: Typo in --arthas-home; pointing at a zip/tar instead of the extracted directory; relative path resolved against an unexpected working directory; missing install dir on a fresh/containerized environment.

Related errors

• {fileName} do not exist, arthas home: {arthasHome}
• batch file do not exist: {batchFile}
• can not find arthas-core.jar under arthasHome: ${arthasHome}
• Failed to create directory within ${TEMP_DIR_ATTEMPTS} attem
• Can not find tools.jar under java home: {javaHome}, please t

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