{"record":{"id":"470aca1d669a12c2","repo":"pinpoint-apm/pinpoint","slug":"boot-method-invoke-failed-error","errorCode":null,"errorMessage":"boot method invoke failed. Error:","messagePattern":"boot method invoke failed\\. Error:","errorType":"exception","errorClass":"BootStrapException","httpStatus":null,"severity":"critical","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/AgentBootLoader.java","lineNumber":63,"sourceCode":"    public Object boot(final AgentOption agentOption) {\n        final Class<?> agentClazz = getBootStrapClass(\"com.navercorp.pinpoint.profiler.Agent\");\n        final Class<?> bootStrapClazz = getBootStrapClass(bootClass);\n        if (!agentClazz.isAssignableFrom(bootStrapClazz)) {\n            throw new IllegalStateException(\"Invalid AgentClass:\" + bootStrapClazz);\n        }\n        final SystemPropertyManager systemPropertyManager = new SystemPropertyManager();\n\n        return executeTemplate.execute(new Callable<Object>() {\n            @Override\n            public Object call() throws Exception {\n                try {\n                    systemPropertyManager.backup(agentOption);\n                    Constructor<?> constructor = bootStrapClazz.getDeclaredConstructor(Map.class);\n                    return constructor.newInstance(agentOption.toMap());\n                } catch (InstantiationException e) {\n                    throw new BootStrapException(\"boot create failed. Error:\" + e.getMessage(), e);\n                } catch (IllegalAccessException e) {\n                    throw new BootStrapException(\"boot method invoke failed. Error:\" + e.getMessage(), e);\n                } finally {\n                    systemPropertyManager.restore();\n                }\n            }\n        });\n    }\n\n    private Class<?> getBootStrapClass(String clazzName) {\n        try {\n            return this.classLoader.loadClass(clazzName);\n        } catch (ClassNotFoundException e) {\n            throw new BootStrapException(\"boot class not found. bootClass:\" + bootClass + \" Error:\" + e.getMessage(), e);\n        }\n    }\n}\n","sourceCodeStart":45,"sourceCodeEnd":79,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/AgentBootLoader.java#L45-L79","documentation":"AgentBootLoader loads the Pinpoint boot class reflectively via constructor.newInstance(agentOption.toMap()). If the constructor call is rejected by IllegalAccessException (e.g. the constructor is not public, or the class/package is not accessible from the caller), it is rethrown as a BootStrapException with the message 'boot method invoke failed. Error:'. This happens inside the boot-classloader execution template, so the agent cannot start at all.","triggerScenarios":"Calling AgentBootLoader.boot where the resolved bootStrapClazz's declared Map constructor is non-public or inaccessible from the boot classloader context (e.g. a custom/non-standard boot class, or a class loaded through the wrong classloader so reflection access checks fail).","commonSituations":"Building a custom Pinpoint agent with a boot class whose constructor is package-private or has reduced visibility; packaging the bootstrap jar so the class ends up in an unexported module (Java 9+); classloader misconfiguration in embedded containers.","solutions":["Make the boot class public and give it a public constructor accepting java.util.Map","Verify the boot class is loaded by the boot classloader that AgentBootLoader passes to getBootStrapClass, not an application classloader","Inspect the wrapped cause (IllegalAccessException) to see the exact access violation; on Java 9+ add JVM --add-opens flags if module access blocks reflection","Confirm the -Dprofiler.pinpoint.agentId style agentArgs map matches what the constructor expects so argument marshalling is not the real problem"],"exampleFix":"// before\nprivate BootStrapClass(Map<String, String> agentOptions) { ... }\n// after\npublic BootStrapClass(Map<String, String> agentOptions) { ... }","handlingStrategy":"try-catch","validationCode":"Class<?> boot = bootClassLoader.loadClass(bootClassName);\nif (!java.lang.reflect.Modifier.isPublic(boot.getModifiers())) throw new IllegalStateException(\"boot class must be public\");\nboot.getDeclaredConstructor(Map.class); // throws NoSuchMethodException early if signature wrong","typeGuard":null,"tryCatchPattern":"try {\n    return constructor.newInstance(agentOption.toMap());\n} catch (IllegalAccessException e) {\n    throw new BootStrapException(\"boot method invoke failed. Error:\" + e.getMessage(), e);\n}","preventionTips":["Make the boot class and its Map constructor public","Ensure the class is loaded via the boot classloader so setAccessible/reflection access checks pass","On Java 9+, keep the boot package exported and add --add-opens if needed"],"tags":["reflection","classloader","java","agent-startup"],"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"}