{"record":{"id":"7e253b79a735ffcd","repo":"pinpoint-apm/pinpoint","slug":"invalid-agentclass","errorCode":null,"errorMessage":"Invalid AgentClass:","messagePattern":"Invalid AgentClass:","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/AgentBootLoader.java","lineNumber":49,"sourceCode":"public class AgentBootLoader {\n\n    private final ClassLoader classLoader;\n\n    private final String bootClass;\n\n    private final ContextClassLoaderExecuteTemplate<Object> executeTemplate;\n\n    public AgentBootLoader(String bootClass, ClassLoader agentClassLoader) {\n        this.bootClass = Objects.requireNonNull(bootClass, \"bootClass\");\n        this.classLoader = Objects.requireNonNull(agentClassLoader, \"agentClassLoader\");\n        this.executeTemplate = new ContextClassLoaderExecuteTemplate<>(agentClassLoader);\n    }\n\n    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            }","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/AgentBootLoader.java#L31-L67","documentation":"AgentBootLoader.boot loads the profiler's Agent implementation class (com.navercorp.pinpoint.profiler.Agent) and the configured bootstrap class, then verifies that the bootstrap class is an instance/subclass of the agent interface/contract. If bootClass is not assignable from agentClazz's hierarchy, an IllegalStateException naming the invalid class is thrown — the configured class does not implement the required Agent contract.","triggerScenarios":"Starting the agent with pinpoint.bootstrapclass (or equivalent bootClass config) pointing to a class that does not implement the expected Agent interface implemented by com.navercorp.pinpoint.profiler.Agent.","commonSituations":"Typo or wrong class name in bootstrap configuration; loading a stale/mixed Pinpoint version where profiler classes were split or renamed; custom bootstrap class missing the Agent interface; classloader loading two incompatible copies of the contract type.","solutions":["Set the bootstrap class config to the correct default (com.navercorp.pinpoint.profiler.DefaultAgent or the documented boot class)","Verify the custom boot class implements the same Agent contract as com.navercorp.pinpoint.profiler.Agent","Align bootstrap and profiler jar versions — do not mix agent module versions","Check for duplicate contract classes on the bootstrap classpath that break assignability"],"exampleFix":"# before\n-Dpinpoint.bootstrapclass=com.navercorp.pinpoint.profiler.CustomAgent (no Agent iface)\n# after\n-Dpinpoint.bootstrapclass=com.navercorp.pinpoint.profiler.DefaultAgent","handlingStrategy":"try-catch","validationCode":"Class<?> boot = Class.forName(bootClassName, true, AgentBootLoader.class.getClassLoader());\nClass<?> agent = Class.forName(\"com.navercorp.pinpoint.profiler.Agent\");\nif (!agent.isAssignableFrom(boot)) throw new IllegalStateException(\"boot class must implement Agent: \" + bootClassName);","typeGuard":null,"tryCatchPattern":"try {\n    return bootLoader.boot(agentOption);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Invalid AgentClass:\")) {\n        logger.error(\"configured bootstrap class does not implement the profiler Agent contract; fix pinpoint.bootstrapclass and align jar versions\", e);\n    } else { throw e; }\n}","preventionTips":["Never override the bootstrap class option unless implementing a custom profiler with the full Agent contract","Keep all pinpoint agent jars from the same release","Verify the boot class loads via the bootstrap classloader (no duplicates on the classpath)"],"tags":["bootstrap","agent-startup","class-assignment"],"backgroundTag":"incompatible-source-type","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}