pinpoint-apm/pinpoint · critical · BootStrapException

boot method invoke failed. Error:

Error message

boot method invoke failed. Error:

What it means

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.

Source

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

    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();
                }
            }
        });
    }

    private Class<?> getBootStrapClass(String clazzName) {
        try {
            return this.classLoader.loadClass(clazzName);
        } catch (ClassNotFoundException e) {
            throw new BootStrapException("boot class not found. bootClass:" + bootClass + " Error:" + e.getMessage(), e);
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Make the boot class public and give it a public constructor accepting java.util.Map
2. Verify the boot class is loaded by the boot classloader that AgentBootLoader passes to getBootStrapClass, not an application classloader
3. Inspect the wrapped cause (IllegalAccessException) to see the exact access violation; on Java 9+ add JVM --add-opens flags if module access blocks reflection
4. Confirm the -Dprofiler.pinpoint.agentId style agentArgs map matches what the constructor expects so argument marshalling is not the real problem

Example fix

// before
private BootStrapClass(Map<String, String> agentOptions) { ... }
// after
public BootStrapClass(Map<String, String> agentOptions) { ... }

Class<?> boot = bootClassLoader.loadClass(bootClassName);
if (!java.lang.reflect.Modifier.isPublic(boot.getModifiers())) throw new IllegalStateException("boot class must be public");
boot.getDeclaredConstructor(Map.class); // throws NoSuchMethodException early if signature wrong

try {
    return constructor.newInstance(agentOption.toMap());
} catch (IllegalAccessException e) {
    throw new BootStrapException("boot method invoke failed. Error:" + e.getMessage(), e);
}

When it happens

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

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

Related errors

• initialize fail Caused by:
• invoke fail Caused by:
• bootstrapClassLoader not found Caused by:
• boot class not found. bootClass: Error:
• execute fail. Error:

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