alibaba/arthas · error · IllegalArgumentException

{fileName} do not exist, arthas home: {arthasHome}

Error message

{fileName} do not exist, arthas home: {arthasHome}

What it means

Bootstrap.verifyArthasHome treats its argument as a candidate installation directory. When the path IS a directory, it checks for three required jars — arthas-core.jar, arthas-agent.jar, arthas-spy.jar. If any is missing it throws IllegalArgumentException naming the missing file and the home path.

Source

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

        }
        for (File file : files) {
            String name = file.getName();
            if (name.startsWith(".") || file.isFile()) {
                continue;
            }
            names.add(name);
        }
        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() {

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Re-download/reinstall the matching Arthas version so the home dir contains all three jars.
2. Point --arthas-home at the directory that actually holds arthas-core.jar, arthas-agent.jar, arthas-spy.jar.
3. If building from source, run the full assemble/package step so all jars are produced.
4. Verify file permissions allow listing/reading the jars.

Example fix

# before
java -jar arthas-boot.jar --arthas-home /opt/arthas-src

# after
java -jar arthas-boot.jar --arthas-home /opt/arthas-lib   # contains the 3 jars

File home = new File(arthasHome);
for (String jar : new String[]{"arthas-core.jar","arthas-agent.jar","arthas-spy.jar"}) {
    if (!new File(home, jar).isFile()) {
        throw new IllegalStateException("arthas home incomplete, missing " + jar);
    }
}

static boolean isCompleteArthasHome(File home) {
    if (home == null || !home.isDirectory()) return false;
    for (String j : new String[]{"arthas-core.jar","arthas-agent.jar","arthas-spy.jar"}) {
        if (!new File(home, j).isFile()) return false;
    }
    return true;
}

try {
    Bootstrap.verifyArthasHome(home);
} catch (IllegalArgumentException e) {
    logger.error("arthas home invalid: {}", home, e);
    // reinstall or repoint home
}

When it happens

Trigger: Running arthas-boot with --use-version or --arthas-home pointing at an incomplete/partial Arthas install where one of the three core jars is absent (e.g. interrupted download, custom build missing spy jar).

Common situations: Corrupted or partial extraction of the arthas distribution; pointing --arthas-home at a source checkout instead of an assembled lib dir; version mismatch where an older layout is missing a jar; permissions hiding a jar from File.exists().

Related errors

• illegal 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/8e8cdb93c7748cfd. Report an issue: GitHub.