{"record":{"id":"64a3d6a2fb316c4a","repo":"pinpoint-apm/pinpoint","slug":"failed-to-load-plugin-class-with-classloader","errorCode":null,"errorMessage":"Failed to load plugin class {} with classLoader {}","messagePattern":"Failed to load plugin class (.+?) with classLoader (.+?)","errorType":"console","errorClass":"PinpointException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/BootstrapClassLoaderHandler.java","lineNumber":56,"sourceCode":"\n    private final Object lock = new Object();\n    private volatile boolean injectedToRoot = false;\n\n    public BootstrapClassLoaderHandler(PluginConfig pluginConfig, InstrumentEngine instrumentEngine) {\n        this.pluginConfig = Objects.requireNonNull(pluginConfig, \"pluginConfig\");\n        this.instrumentEngine = Objects.requireNonNull(instrumentEngine, \"instrumentEngine\");\n    }\n\n    @Override\n    @SuppressWarnings(\"unchecked\")\n    public <T> Class<? extends T> injectClass(ClassLoader classLoader, String className) {\n        if (classLoader != Object.class.getClassLoader()) {\n            throw new IllegalStateException(\"not BootStrapClassLoader\");\n        }\n        try {\n            return (Class<T>) injectClass0(className);\n        } catch (Exception e) {\n            logger.warn(\"Failed to load plugin class {} with classLoader {}\", className, classLoader, e);\n            throw new PinpointException(\"Failed to load plugin class \" + className + \" with classLoader \" + classLoader, e);\n        }\n    }\n\n    private Class<?> injectClass0(String className) throws IllegalArgumentException, ClassNotFoundException {\n        appendToBootstrapClassLoaderSearch();\n        return Class.forName(className, false, null);\n    }\n\n    private void appendToBootstrapClassLoaderSearch() {\n        // DCL\n        if (injectedToRoot) {\n            return;\n        }\n        synchronized (lock) {\n            if (this.injectedToRoot == false) {\n                instrumentEngine.appendToBootstrapClassPath(pluginConfig.getPluginJarFile());\n                // Memory visibility WARNING","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/BootstrapClassLoaderHandler.java#L38-L74","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the wrapped cause (e) in the PinpointException — fix the underlying ClassNotFoundException/LinkageError.","Ensure the plugin jar containing the class is actually appended to the bootstrap classloader search (appendToBootstrapClassLoaderSearch).","Verify the class really should be bootstrap-loaded; if it needs app classes, it should be handled by PlainClassLoaderHandler instead.","Confirm the fully-qualified class name and plugin configuration are correct."],"exampleFix":"// before\nthrow new PinpointException(\"Failed to load plugin class \" + className + \" with classLoader \" + classLoader, e);\n// after\n// inspect cause first:\nlogger.error(\"plugin class={} bootstrap load failed, cause={}\", className, e.getCause());\n// then fix classpath/config so the class is on the bootstrap search path","handlingStrategy":"try-catch","validationCode":"if (classLoader != Object.class.getClassLoader()) { throw new IllegalArgumentException(\"bootstrap loader required\"); }\nif (!pluginJarOnBootstrapPath(pluginJar)) { throw new IllegalStateException(\"plugin jar not on bootstrap classpath\"); }","typeGuard":null,"tryCatchPattern":"try { return injector.injectClass(classLoader, className); } catch (PinpointException e) { log.error(\"bootstrap load failed: {}\", e.getCause(), e); throw e; }","preventionTips":["Confirm plugin jars are registered for bootstrap classpath search before use","Only bootstrap-load classes with no application-classloader dependencies","Validate class names in plugin config at startup","Read the wrapped cause, not just the message"],"tags":["classloader","plugin","bootstrap","class-not-found"],"backgroundTag":"class-not-found","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"}