{"record":{"id":"bfd96e48f5896cb0","repo":"pinpoint-apm/pinpoint","slug":"not-found-bfd96e","errorCode":null,"errorMessage":" not found","messagePattern":" not found","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/agentdir/BootDir.java","lineNumber":57,"sourceCode":"        Objects.requireNonNull(baseDir, \"baseDir\");\n        Objects.requireNonNull(jarDescriptions, \"jarDescriptions\");\n        this.jars = verify(baseDir, jarDescriptions);\n    }\n\n    private List<Path> verify(Path baseDir, List<JarDescription> jarDescriptions) {\n        final List<Path> jarFiles = FileUtils.listFiles(baseDir, \"*.jar\");\n        if (jarFiles.isEmpty()) {\n            logger.info(baseDir + \" is empty\");\n            return null;\n        }\n\n        List<Path> resolvedJarList = new ArrayList<>(jarDescriptions.size());\n        for (JarDescription jarDescription : jarDescriptions) {\n            final Path jarFileName = find(jarFiles, jarDescription);\n            if (jarFileName == null) {\n                final String errorMessage = jarDescription.getSimplePattern() + \" not found\";\n                if (jarDescription.isRequired()) {\n                    throw new IllegalStateException(errorMessage);\n                }\n            } else {\n                resolvedJarList.add(jarFileName.toAbsolutePath());\n            }\n        }\n        return resolvedJarList;\n    }\n\n    private Path find(List<Path> jarFiles, final JarDescription jarDescription) {\n        final String jarName = jarDescription.getJarName();\n        final Pattern pattern = jarDescription.getVersionPattern();\n\n        final List<Path> jarPathList = findFileByPattern(jarFiles, pattern);\n        if (jarPathList.isEmpty()) {\n            logger.info(jarName + \" not found.\");\n            return null;\n        }\n        if (jarPathList.size() == 1) {","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/agentdir/BootDir.java#L39-L75","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Check the agent directory for the JAR named in the message and restore the full, unmodified pinpoint-agent distribution.","Re-download/re-copy the complete agent distribution matching your Pinpoint version instead of hand-picking files.","If JAR names were customized, update the JarDescription patterns to match the actual file names, or revert the renames.","Verify you are pointing the agent at the correct -Dpinpoint.agentId/agent dir path (the directory actually containing the lib JARs)."],"exampleFix":"// before: agent dir missing pinpoint-bootstrap-core-x.y.z.jar after manual cleanup\nrm $AGENT_DIR/boot/pinpoint-bootstrap-core-2.5.0.jar\n// after: restore the full distribution so all required boot JARs exist\ncp pinpoint-agent-2.5.0/boot/*.jar $AGENT_DIR/boot/","handlingStrategy":"validation","validationCode":"// Verify all required boot JARs exist before bootstrapping\nboolean missing = jarDescriptions.stream()\n    .filter(JarDescription::isRequired)\n    .anyMatch(d -> find(jarFiles, d) == null);\nif (missing) {\n    throw new IllegalStateException(\"Required agent JAR(s) missing from \" + agentDir);\n}","typeGuard":null,"tryCatchPattern":"// Wrap bootstrap startup\ntry {\n    bootDir.verify();\n} catch (IllegalStateException e) {\n    logger.error(\"Agent boot failed: {}\", e.getMessage());\n    // abort startup; do not attempt to run partially bootstrapped agent\n    throw e;\n}","preventionTips":["Deploy the agent distribution as a whole; never hand-delete individual lib/boot JARs.","Keep JAR file names unmodified across upgrades — patterns in JarDescription depend on them.","Add a pre-start smoke test that runs BootDir.verify() in CI before shipping the agent bundle.","Confirm the configured agent directory path points at the extracted distribution root."],"tags":["bootstrap","classpath","missing-jar","startup"],"backgroundTag":"file-not-found","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}