pinpoint-apm/pinpoint · error · PinpointException

Failed to load plugin class {} with classLoader {}

Error message

Failed to load plugin class {} with classLoader {}

What it means

BootstrapClassLoaderHandler.injectClass loads a plugin class that must live on the bootstrap classpath. Any failure during injectClass0 (append to bootstrap search failing, ClassNotFoundException, linkage problems) is logged, wrapped in a PinpointException, and rethrown. This means the plugin class could not be resolved in the bootstrap classloader context.

Source

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

    private final Object lock = new Object();
    private volatile boolean injectedToRoot = false;

    public BootstrapClassLoaderHandler(PluginConfig pluginConfig, InstrumentEngine instrumentEngine) {
        this.pluginConfig = Objects.requireNonNull(pluginConfig, "pluginConfig");
        this.instrumentEngine = Objects.requireNonNull(instrumentEngine, "instrumentEngine");
    }

    @Override
    @SuppressWarnings("unchecked")
    public <T> Class<? extends T> injectClass(ClassLoader classLoader, String className) {
        if (classLoader != Object.class.getClassLoader()) {
            throw new IllegalStateException("not BootStrapClassLoader");
        }
        try {
            return (Class<T>) injectClass0(className);
        } catch (Exception e) {
            logger.warn("Failed to load plugin class {} with classLoader {}", className, classLoader, e);
            throw new PinpointException("Failed to load plugin class " + className + " with classLoader " + classLoader, e);
        }
    }

    private Class<?> injectClass0(String className) throws IllegalArgumentException, ClassNotFoundException {
        appendToBootstrapClassLoaderSearch();
        return Class.forName(className, false, null);
    }

    private void appendToBootstrapClassLoaderSearch() {
        // DCL
        if (injectedToRoot) {
            return;
        }
        synchronized (lock) {
            if (this.injectedToRoot == false) {
                instrumentEngine.appendToBootstrapClassPath(pluginConfig.getPluginJarFile());
                // Memory visibility WARNING

View on GitHub (pinned to 744c3d3075)

Solutions

1. Check the wrapped cause (e) in the PinpointException — fix the underlying ClassNotFoundException/LinkageError.
2. Ensure the plugin jar containing the class is actually appended to the bootstrap classloader search (appendToBootstrapClassLoaderSearch).
3. Verify the class really should be bootstrap-loaded; if it needs app classes, it should be handled by PlainClassLoaderHandler instead.
4. Confirm the fully-qualified class name and plugin configuration are correct.

Example fix

// before
throw new PinpointException("Failed to load plugin class " + className + " with classLoader " + classLoader, e);
// after
// inspect cause first:
logger.error("plugin class={} bootstrap load failed, cause={}", className, e.getCause());
// then fix classpath/config so the class is on the bootstrap search path

if (classLoader != Object.class.getClassLoader()) { throw new IllegalArgumentException("bootstrap loader required"); }
if (!pluginJarOnBootstrapPath(pluginJar)) { throw new IllegalStateException("plugin jar not on bootstrap classpath"); }

try { return injector.injectClass(classLoader, className); } catch (PinpointException e) { log.error("bootstrap load failed: {}", e.getCause(), e); throw e; }

When it happens

Trigger: injectClass called with the bootstrap classloader (null/Object's loader) but the class is absent from bootstrap classpath resources, or appendToBootstrapClassLoaderSearch failed, or the class failed to link/initialize.

Common situations: Plugin jar not registered on the bootstrap classpath (bootclass path config wrong); className misconfigured; plugin expects app classloader classes while being forced onto the bootstrap loader; NoClassDefFoundError from missing dependencies of the plugin class.

Related errors

• not found Caused by:
• Failed to load plugin class ${className} with classLoader ${
• ${ex.getMessage()}
• Failed to load plugin class {} with classLoader {}
• not found Caused by:

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