pinpoint-apm/pinpoint · error

Invalid pinpoint-bootstrap.jar:

Error message

Invalid pinpoint-bootstrap.jar:

What it means

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.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/PinpointBootStrap.java:89

        this.instrumentation = Objects.requireNonNull(instrumentation, "instrumentation");
    }


    private void start() {
        logger.info("pinpoint agentArgs:" + agentArgs);
        logger.info("PinpointBootStrap.ClassLoader:" + PinpointBootStrap.class.getClassLoader());
        logger.info("ContextClassLoader:" + Thread.currentThread().getContextClassLoader());

        final JavaAgentPathResolver javaAgentPathResolver = JavaAgentPathResolver.newJavaAgentPathResolver();
        final Path agentPath = javaAgentPathResolver.resolveJavaAgentPath();
        logger.info("JavaAgentPath:" + agentPath);
        if (!Files.exists(agentPath)) {
            logger.warn("AgentPath not found path:" + agentPath);
        }

        if (Object.class.getClassLoader() != PinpointBootStrap.class.getClassLoader()) {
            // TODO bug : location is null
            logger.warn("Invalid pinpoint-bootstrap.jar:" + agentArgs);
            return;
        }

        final Map<String, String> agentArgsMap = argsToMap(agentArgs);

        final ClassPathResolver classPathResolver = new AgentDirBaseClassPathResolver(agentPath);

        final AgentDirectory agentDirectory = resolveAgentDir(classPathResolver);
        if (agentDirectory == null) {
            logger.warn("Agent Directory Verify fail. skipping agent loading.");
            logPinpointAgentLoadFail();
            return;
        }
        BootDir bootDir = agentDirectory.getBootDir();
        appendToBootstrapClassLoader(instrumentation, bootDir);

        ClassLoader parentClassLoader = getParentClassLoader();
        PinpointStarter bootStrap = new PinpointStarter(instrumentation, parentClassLoader, agentArgsMap, agentDirectory);

View on GitHub (pinned to 744c3d3075)

Solutions

1. Remove pinpoint-bootstrap.jar from the application classpath/fat jar
2. Pass it only via -javaagent:/path/to/pinpoint-bootstrap.jar
3. Exclude pinpoint bootstrap/transitive dependencies when shading (relocation or exclusion rules)
4. Restart the JVM after fixing how the jar is loaded

Example fix

// before (maven shade embedding the agent)
<artifactItem>
  <groupId>com.navercorp.pinpoint</groupId>
  <artifactId>pinpoint-bootstrap</artifactId>
</artifactItem>
// after — remove the inclusion; launch with:
java -javaagent:/opt/pinpoint-agent/pinpoint-bootstrap.jar -jar app.jar

// shell: ensure the jar is not on the app classpath
echo "$CLASSPATH" | tr ':' '\n' | grep -q pinpoint-bootstrap && echo "remove pinpoint-bootstrap from classpath; use -javaagent"

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• boot class not found. bootClass: Error:
• J9BootLoader create fail Caused by:
• initialize fail Caused by:
• invoke fail Caused by:
• bootstrapClassLoader not found Caused by:

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