pinpoint-apm/pinpoint · error · RuntimeException

${ex.getMessage()}

Error message

${ex.getMessage()}

What it means

RuntimeException thrown by BootstrapCore.loadClass when Class.forName on the bootstrap class loader throws ClassNotFoundException. The message is just the original exception message (the missing class name); the cause carries the ClassNotFoundException. It signals that a bootstrap-level class required by instrumentation is not visible to the bootstrap class loader.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/BootstrapCore.java:70

    public boolean isBootstrapPackageByInternalName(String internalClassName) {
        return bootstrapPackage.isBootstrapPackageByInternalName(internalClassName);
    }

    public InputStream openStream(String internalClassName) {
        return bootstrapRepository.openStream(internalClassName);
    }

    public <T> Class<? extends T> loadClass(String className) {
        try {
            if (isDebug) {
                logger.debug("loadClass:{}", className);
            }
            return (Class<T>) Class.forName(className, false, bootstrapClassLoader);
        } catch (ClassNotFoundException ex) {
            if (isDebug) {
                logger.debug("ClassNotFound {} cl:{}", ex.getMessage(), bootstrapClassLoader);
            }
            throw new RuntimeException(ex.getMessage(), ex);
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Ensure appendToBootstrapClassLoaderSearch is invoked and the jar containing the class is included
2. Verify the exact class name and that it exists in the bootstrap jar for the current agent version
3. Inspect the cause chain (ClassNotFoundException) to confirm which class is missing
4. Upgrade/rebuild the agent so bootstrap classes match the instrumentation code

Example fix

// before
bootstrapCore.loadClass("com.bootstrap.MissingHelper");
// after
bootstrapCore.loadClass("com.bootstrap.Helper"); // class present in bootstrap jar

try {
    return bootstrapCore.loadClass(className);
} catch (RuntimeException e) {
    if (e.getCause() instanceof ClassNotFoundException) {
        logger.error("{} not visible to bootstrap class loader; ensure bootstrap jar is appended", className, e);
    }
    throw e;
}

When it happens

Trigger: loadClass is called for a class that is not present in the bootstrap class loader search path; appendToBootstrapClassLoaderSearch did not include the jar containing the class; the class name is wrong or was renamed.

Common situations: Instrumenting JDK classes whose helper classes must be bootstrap-loaded but the jar was not appended; agent upgrade renamed an internal bootstrap class; class name typos in instrumentation configuration.

Related errors

• Failed to load plugin class ${className} with classLoader ${
• Failed to load plugin class {} with classLoader {}
• not found Caused by:
• not found Caused by:
• not BootStrapClassLoader

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