pinpoint-apm/pinpoint · critical · IllegalStateException

not found

Error message

 not found

What it means

Pinpoint's AgentDirBaseClassPathResolver.resolve() requires the bootstrap jar path to point to an existing regular file. When Files.isRegularFile(bootstrapJarPath) is false (missing file, or a directory/symlink to nothing), it throws IllegalStateException '<path> not found'. It signals the agent was launched with a bad bootstrap jar location so class path resolution cannot proceed.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/agentdir/AgentDirBaseClassPathResolver.java:66

    private final JarDescription bootstrapJava9 = new JarDescription("pinpoint-bootstrap-java9", false);
    private final JarDescription bootstrapJava9internal = new JarDescription("pinpoint-bootstrap-java9-internal", false);
    private final JarDescription bootstrapJava15 = new JarDescription("pinpoint-bootstrap-java15", false);
    private final JarDescription bootstrapJava16 = new JarDescription("pinpoint-bootstrap-java16", false);
    private final List<JarDescription> bootJarDescriptions = Arrays.asList(commons, commonsConfig, bootstrapCore, annotations, bootstrapJava9, bootstrapJava9internal, bootstrapJava15, bootstrapJava16);

    private final Path bootstrapJarPath;



    public AgentDirBaseClassPathResolver(Path bootstrapJarPath) {
        this.bootstrapJarPath = Objects.requireNonNull(bootstrapJarPath, "classPath");
    }


    @Override
    public AgentDirectory resolve() {
        if (!Files.isRegularFile(bootstrapJarPath)) {
            throw new IllegalStateException(bootstrapJarPath + " not found");
        }

        // find bootstrap.jar
        final Path bootstrapJarName = this.findBootstrapJar(this.bootstrapJarPath);
        if (bootstrapJarName == null) {
            throw new IllegalStateException(bootstrap.getSimplePattern() + " not found.");
        }

        final Path agentDirPath = getAgentDirPath(this.bootstrapJarPath);

        final BootDir bootDir = resolveBootDir(agentDirPath);

        final Path agentLibPath = getAgentLibPath(agentDirPath);
        final List<Path> libs = resolveLib(agentLibPath);

        Path agentPluginPath = getAgentPluginPath(agentDirPath);
        final List<Path> plugins = resolvePlugins(agentPluginPath);

View on GitHub (pinned to 744c3d3075)

Solutions

1. Verify the path exists and is a regular file: ls -l <bootstrapJarPath>; correct the -javaagent / boot jar path in the start script
2. Reinstall or re-extract the Pinpoint agent distribution so pinpoint-bootstrap*.jar is present in the agent dir
3. Check for symlinks pointing to a moved/deleted location and fix the symlink or use the real path
4. Ensure the user running the JVM has execute/read permission on the agent directory

Example fix

// before
-javaagent:/opt/pinpoint-agent/pinpoint-bootstrap.jar
// after
-javaagent:/opt/pinpoint-agent-2.5.0/pinpoint-bootstrap.jar   # path verified with ls -l

Path boot = Paths.get("/opt/pinpoint-agent/pinpoint-bootstrap.jar");
if (!Files.isRegularFile(boot)) {
    throw new IllegalArgumentException("bootstrap jar missing or not a file: " + boot);
}

boolean isValidBootstrapJar(Path p) {
    return p != null && Files.isRegularFile(p);
}

try {
    AgentDirectory dir = resolver.resolve();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().endsWith(" not found")) {
        // log bootstrapJarPath, fail fast with corrected path instructions
    }
    throw e;
}

When it happens

Trigger: Starting the Pinpoint agent with a -javaagent or bootClass path that does not exist, points to a directory, or was moved/renamed; the resolved bootstrapJarPath argument to the constructor references a non-regular file.

Common situations: Wrong PINPOINT_AGENT path in launch scripts or JVM args; agent directory partially copied (bootstrap.jar missing); typos like pinpoint-bootstrap.jar vs pinpoint-bootstrap-core.jar; file deleted after an upgrade while an old start script still points at it.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• not found.
• agentDirPath is null
• lib dir is empty
• can read
• !/ not found

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/00bb0265f95769c0. Report an issue: GitHub.