{"record":{"id":"1b9e5f6aff04fdf5","repo":"pinpoint-apm/pinpoint","slug":"invalid-pinpoint-bootstrap-jar","errorCode":null,"errorMessage":"Invalid pinpoint-bootstrap.jar:","messagePattern":"Invalid pinpoint-bootstrap\\.jar:","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/PinpointBootStrap.java","lineNumber":89,"sourceCode":"        this.instrumentation = Objects.requireNonNull(instrumentation, \"instrumentation\");\n    }\n\n\n    private void start() {\n        logger.info(\"pinpoint agentArgs:\" + agentArgs);\n        logger.info(\"PinpointBootStrap.ClassLoader:\" + PinpointBootStrap.class.getClassLoader());\n        logger.info(\"ContextClassLoader:\" + Thread.currentThread().getContextClassLoader());\n\n        final JavaAgentPathResolver javaAgentPathResolver = JavaAgentPathResolver.newJavaAgentPathResolver();\n        final Path agentPath = javaAgentPathResolver.resolveJavaAgentPath();\n        logger.info(\"JavaAgentPath:\" + agentPath);\n        if (!Files.exists(agentPath)) {\n            logger.warn(\"AgentPath not found path:\" + agentPath);\n        }\n\n        if (Object.class.getClassLoader() != PinpointBootStrap.class.getClassLoader()) {\n            // TODO bug : location is null\n            logger.warn(\"Invalid pinpoint-bootstrap.jar:\" + agentArgs);\n            return;\n        }\n\n        final Map<String, String> agentArgsMap = argsToMap(agentArgs);\n\n        final ClassPathResolver classPathResolver = new AgentDirBaseClassPathResolver(agentPath);\n\n        final AgentDirectory agentDirectory = resolveAgentDir(classPathResolver);\n        if (agentDirectory == null) {\n            logger.warn(\"Agent Directory Verify fail. skipping agent loading.\");\n            logPinpointAgentLoadFail();\n            return;\n        }\n        BootDir bootDir = agentDirectory.getBootDir();\n        appendToBootstrapClassLoader(instrumentation, bootDir);\n\n        ClassLoader parentClassLoader = getParentClassLoader();\n        PinpointStarter bootStrap = new PinpointStarter(instrumentation, parentClassLoader, agentArgsMap, agentDirectory);","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/PinpointBootStrap.java#L71-L107","documentation":"The bootstrap checks that PinpointBootStrap was loaded by the bootstrap (null) class loader; if not, the jar was loaded on the application classpath instead of via -javaagent, so it logs this warning and aborts agent loading. Instrumentation cannot proceed from the wrong class loader.","triggerScenarios":"pinpoint-bootstrap.jar added to the application classpath (-cp or in a fat jar) instead of being passed with -javaagent; a shaded jar embedding pinpoint classes; framework classloader (e.g. app server) loading the bootstrap class itself.","commonSituations":"Bundling pinpoint classes into a Spring Boot fat jar; adding the jar to WEB-INF/lib or the app server's shared lib; IDE run configurations that add the jar as a dependency rather than an agent.","solutions":["Remove pinpoint-bootstrap.jar from the application classpath/fat jar","Pass it only via -javaagent:/path/to/pinpoint-bootstrap.jar","Exclude pinpoint bootstrap/transitive dependencies when shading (relocation or exclusion rules)","Restart the JVM after fixing how the jar is loaded"],"exampleFix":"// before (maven shade embedding the agent)\n<artifactItem>\n  <groupId>com.navercorp.pinpoint</groupId>\n  <artifactId>pinpoint-bootstrap</artifactId>\n</artifactItem>\n// after — remove the inclusion; launch with:\njava -javaagent:/opt/pinpoint-agent/pinpoint-bootstrap.jar -jar app.jar","handlingStrategy":"validation","validationCode":"// shell: ensure the jar is not on the app classpath\necho \"$CLASSPATH\" | tr ':' '\\n' | grep -q pinpoint-bootstrap && echo \"remove pinpoint-bootstrap from classpath; use -javaagent\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only ever load the bootstrap jar via -javaagent","Exclude pinpoint dependencies from fat jars/shaded artifacts","In IDEs, configure the agent under VM options, not project dependencies"],"tags":["java","javaagent","classpath","classloader"],"backgroundTag":"invalid-config-value","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"}