pinpoint-apm/pinpoint · error · IllegalStateException

not BootStrapClassLoader

Error message

not BootStrapClassLoader

What it means

IllegalStateException thrown by BootstrapClassLoaderHandler.injectClass when the passed class loader is not the bootstrap class loader (represented by Object.class.getClassLoader() == null). This handler only serves classes that must be injected into the bootstrap class loader; any other class loader is a programming error by the caller.

Source

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

    private final Logger logger = LogManager.getLogger(this.getClass());

    private final PluginConfig pluginConfig;
    private final InstrumentEngine instrumentEngine;

    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;

View on GitHub (pinned to 744c3d3075)

Solutions

1. Ensure this handler is only invoked for classes marked for bootstrap injection (loader == null)
2. Route non-bootstrap classes to the appropriate ClassInjector (plugin/ProfilerClassLoader handler)
3. Fix the class loader detection logic that selected the bootstrap handler for this class

Example fix

// before
injector.injectClass(targetClassLoader, "com.bootstrap.Helper");
// after
if (targetClassLoader == null) {
    injector.injectClass(targetClassLoader, "com.bootstrap.Helper");
} else {
    pluginInjector.injectClass(targetClassLoader, "com.plugin.Helper");
}

if (classLoader != null) {
    throw new IllegalArgumentException("bootstrap injector requires null classLoader");
}

boolean isBootstrapClassLoader(ClassLoader cl) {
    return cl == Object.class.getClassLoader(); // null
}

try {
    return handler.injectClass(classLoader, className);
} catch (IllegalStateException e) {
    if ("not BootStrapClassLoader".equals(e.getMessage())) {
        return pluginHandler.injectClass(classLoader, className);
    }
    throw e;
}

When it happens

Trigger: Calling injectClass with an application or plugin class loader instead of null (bootstrap); the class loader routing logic in the instrumentation engine dispatching to the wrong handler for a class expected to be bootstrap-loaded.

Common situations: Plugin code manually calling ClassInjector variants with the wrong loader; a target class mistakenly detected as a bootstrap class; custom engine wiring dispatching helper classes to the bootstrap handler.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

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