pinpoint-apm/pinpoint · critical · IllegalStateException

Invalid AgentClass:

Error message

Invalid AgentClass:

What it means

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.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/AgentBootLoader.java:49

public class AgentBootLoader {

    private final ClassLoader classLoader;

    private final String bootClass;

    private final ContextClassLoaderExecuteTemplate<Object> executeTemplate;

    public AgentBootLoader(String bootClass, ClassLoader agentClassLoader) {
        this.bootClass = Objects.requireNonNull(bootClass, "bootClass");
        this.classLoader = Objects.requireNonNull(agentClassLoader, "agentClassLoader");
        this.executeTemplate = new ContextClassLoaderExecuteTemplate<>(agentClassLoader);
    }

    public Object boot(final AgentOption agentOption) {
        final Class<?> agentClazz = getBootStrapClass("com.navercorp.pinpoint.profiler.Agent");
        final Class<?> bootStrapClazz = getBootStrapClass(bootClass);
        if (!agentClazz.isAssignableFrom(bootStrapClazz)) {
            throw new IllegalStateException("Invalid AgentClass:" + bootStrapClazz);
        }
        final SystemPropertyManager systemPropertyManager = new SystemPropertyManager();

        return executeTemplate.execute(new Callable<Object>() {
            @Override
            public Object call() throws Exception {
                try {
                    systemPropertyManager.backup(agentOption);
                    Constructor<?> constructor = bootStrapClazz.getDeclaredConstructor(Map.class);
                    return constructor.newInstance(agentOption.toMap());
                } catch (InstantiationException e) {
                    throw new BootStrapException("boot create failed. Error:" + e.getMessage(), e);
                } catch (IllegalAccessException e) {
                    throw new BootStrapException("boot method invoke failed. Error:" + e.getMessage(), e);
                } finally {
                    systemPropertyManager.restore();
                }
            }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Set the bootstrap class config to the correct default (com.navercorp.pinpoint.profiler.DefaultAgent or the documented boot class)
2. Verify the custom boot class implements the same Agent contract as com.navercorp.pinpoint.profiler.Agent
3. Align bootstrap and profiler jar versions — do not mix agent module versions
4. Check for duplicate contract classes on the bootstrap classpath that break assignability

Example fix

# before
-Dpinpoint.bootstrapclass=com.navercorp.pinpoint.profiler.CustomAgent (no Agent iface)
# after
-Dpinpoint.bootstrapclass=com.navercorp.pinpoint.profiler.DefaultAgent

Class<?> boot = Class.forName(bootClassName, true, AgentBootLoader.class.getClassLoader());
Class<?> agent = Class.forName("com.navercorp.pinpoint.profiler.Agent");
if (!agent.isAssignableFrom(boot)) throw new IllegalStateException("boot class must implement Agent: " + bootClassName);

try {
    return bootLoader.boot(agentOption);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Invalid AgentClass:")) {
        logger.error("configured bootstrap class does not implement the profiler Agent contract; fix pinpoint.bootstrapclass and align jar versions", e);
    } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• boot create failed. Error:
• handler
• boot method invoke failed. Error:
• boot class not found. bootClass: Error:
• Unknown AgentType:

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