pinpoint-apm/pinpoint · error · IllegalStateException

not found.

Error message

 not found.

What it means

After confirming the bootstrap jar file exists, resolve() scans its directory for a file matching the bootstrap jar simple pattern via findBootstrapJar(). If no matching jar is found it throws IllegalStateException '<pattern> not found.' This means the agent directory layout is broken — the bootstrap jar is present at the given path but no file matching the expected name pattern exists there.

Source

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

    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);

        final AgentDirectory agentDirectory =
                new AgentDirectory(bootstrapJarName, this.bootstrapJarPath, agentDirPath, bootDir, libs, plugins);

        return agentDirectory;
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Restore the original bootstrap jar filename (e.g. pinpoint-bootstrap-x.y.z.jar) so it matches the expected simple pattern
2. Re-extract the official Pinpoint agent distribution instead of a manually assembled directory
3. Check the resolved bootstrap jar name against the Pinpoint version's expected pattern and align your build/packaging
4. Point the agent at an unmodified agent directory from a release archive

Example fix

// before
mv pinpoint-bootstrap-2.5.0.jar bootstrap.jar
// after
# keep the original name expected by the pattern
pinpoint-bootstrap-2.5.0.jar  (unmodified release layout)

try (var stream = Files.list(agentDir)) {
    boolean found = stream.anyMatch(p -> p.getFileName().toString().startsWith("pinpoint-bootstrap"));
    if (!found) throw new IllegalStateException("no bootstrap jar matching pattern in " + agentDir);
}

boolean hasBootstrapJar(Path agentDir) throws IOException {
    if (agentDir == null || !Files.isDirectory(agentDir)) return false;
    try (var s = Files.list(agentDir)) {
        return s.anyMatch(p -> p.getFileName().toString().contains("pinpoint-bootstrap"));
    }
}

try {
    AgentDirectory dir = resolver.resolve();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().endsWith(" not found.")) {
        // inspect agent dir contents vs expected bootstrap pattern
    }
    throw e;
}

When it happens

Trigger: The jar at bootstrapJarPath exists but its filename does not match bootstrap.getSimplePattern() (e.g. renamed or a non-standard build); findBootstrapJar returns null because the directory contents were replaced with jars of unexpected names.

Common situations: Renaming pinpoint-bootstrap.jar during custom packaging; mixing files from different Pinpoint versions after a manual upgrade; a build producing a snapshot jar name that no longer matches the pattern.

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/d1e34f4235f68341. Report an issue: GitHub.