{"record":{"id":"2447f90532956510","repo":"pinpoint-apm/pinpoint","slug":"failed-to-load-plugin-class-classname-with-clas","errorCode":null,"errorMessage":"Failed to load plugin class ${className} with classLoader ${classLoader}","messagePattern":"Failed to load plugin class (.+?) with classLoader (.+?)","errorType":"exception","errorClass":"PinpointException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/BootstrapClassLoaderHandler.java","lineNumber":57,"sourceCode":"    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\n                // Reordering is not recommended.","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/BootstrapClassLoaderHandler.java#L39-L75","documentation":"PinpointException wrapping any failure while injecting a class into the bootstrap class loader. After appending the bootstrap jar to the search path, Class.forName(className, false, null) failed (typically ClassNotFoundException), so the handler logs a warning and rethrows a descriptive PinpointException including the class name and class loader.","triggerScenarios":"injectClass0 fails with ClassNotFoundException because the class is not in the bootstrap jar appended via appendToBootstrapClassLoaderSearch; a helper class was not packaged into the bootstrap jar at build/deploy time.","commonSituations":"Rebuilt agent where a bootstrap helper class was renamed or removed; plugin declaring a bootstrap class that was never added to pinpoint's bootstrap jar; packaging scripts excluding the class.","solutions":["Verify the class is packaged in the bootstrap jar that gets appended to the bootstrap class loader search","Rebuild/redeploy the agent so the bootstrap jar contains the helper class","Check the wrapped cause (logged warn) for the underlying reason","Correct the class name if it was renamed in a recent version"],"exampleFix":"// before\n<exclude>com/bootstrap/OldHelper.class</exclude>\n// after\n<include>com/bootstrap/Helper.class</include> <!-- packaged into bootstrap jar -->","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    return handler.injectClass(classLoader, className);\n} catch (PinpointException e) {\n    logger.error(\"bootstrap class {} missing from bootstrap jar; cause: {}\", className, e.getCause(), e);\n    throw e;\n}","preventionTips":["Verify packaging includes every bootstrap helper class in the bootstrap jar","Re-run integration tests after renaming any bootstrap-internal class","Log and check the cause (usually ClassNotFoundException) at startup"],"tags":["classloader","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-14T11:17:12.474Z"}