pinpoint-apm/pinpoint · critical · IllegalStateException

not found

Error message

 not found

What it means

BootDir.verify() resolves each required Pinpoint agent JAR (via JarDescription patterns) against the files found in the agent directory. When a JAR whose JarDescription.isRequired() is true cannot be located, it throws IllegalStateException with "<simplePattern> not found". This guards agent bootstrapping: starting without a core agent JAR would produce a broken runtime, so boot fails fast.

Source

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

        Objects.requireNonNull(baseDir, "baseDir");
        Objects.requireNonNull(jarDescriptions, "jarDescriptions");
        this.jars = verify(baseDir, jarDescriptions);
    }

    private List<Path> verify(Path baseDir, List<JarDescription> jarDescriptions) {
        final List<Path> jarFiles = FileUtils.listFiles(baseDir, "*.jar");
        if (jarFiles.isEmpty()) {
            logger.info(baseDir + " is empty");
            return null;
        }

        List<Path> resolvedJarList = new ArrayList<>(jarDescriptions.size());
        for (JarDescription jarDescription : jarDescriptions) {
            final Path jarFileName = find(jarFiles, jarDescription);
            if (jarFileName == null) {
                final String errorMessage = jarDescription.getSimplePattern() + " not found";
                if (jarDescription.isRequired()) {
                    throw new IllegalStateException(errorMessage);
                }
            } else {
                resolvedJarList.add(jarFileName.toAbsolutePath());
            }
        }
        return resolvedJarList;
    }

    private Path find(List<Path> jarFiles, final JarDescription jarDescription) {
        final String jarName = jarDescription.getJarName();
        final Pattern pattern = jarDescription.getVersionPattern();

        final List<Path> jarPathList = findFileByPattern(jarFiles, pattern);
        if (jarPathList.isEmpty()) {
            logger.info(jarName + " not found.");
            return null;
        }
        if (jarPathList.size() == 1) {

View on GitHub (pinned to 744c3d3075)

Solutions

1. Check the agent directory for the JAR named in the message and restore the full, unmodified pinpoint-agent distribution.
2. Re-download/re-copy the complete agent distribution matching your Pinpoint version instead of hand-picking files.
3. If JAR names were customized, update the JarDescription patterns to match the actual file names, or revert the renames.
4. Verify you are pointing the agent at the correct -Dpinpoint.agentId/agent dir path (the directory actually containing the lib JARs).

Example fix

// before: agent dir missing pinpoint-bootstrap-core-x.y.z.jar after manual cleanup
rm $AGENT_DIR/boot/pinpoint-bootstrap-core-2.5.0.jar
// after: restore the full distribution so all required boot JARs exist
cp pinpoint-agent-2.5.0/boot/*.jar $AGENT_DIR/boot/

// Verify all required boot JARs exist before bootstrapping
boolean missing = jarDescriptions.stream()
    .filter(JarDescription::isRequired)
    .anyMatch(d -> find(jarFiles, d) == null);
if (missing) {
    throw new IllegalStateException("Required agent JAR(s) missing from " + agentDir);
}

// Wrap bootstrap startup
try {
    bootDir.verify();
} catch (IllegalStateException e) {
    logger.error("Agent boot failed: {}", e.getMessage());
    // abort startup; do not attempt to run partially bootstrapped agent
    throw e;
}

When it happens

Trigger: Calling BootDir.verify()/bootstrapping the agent when a JAR matching a required JarDescription's simplePattern is absent from the scanned directory — e.g. the find(jarFiles, jarDescription) lookup returns null for a required entry. Optional JARs (isRequired()==false) do not trigger this.

Common situations: Incomplete or corrupted pinpoint-agent deployment (a required lib JAR was deleted or never copied); renaming agent module JARs manually; version upgrades where the packaged JAR file name changed (pattern no longer matches); extracting the agent distribution partially (disk full, antivirus quarantine).

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

• handler
• Invalid AgentClass:
• boot create failed. Error:
• boot class not found. bootClass: Error:
• ModuleSupportFactory not found Caused by:

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