pinpoint-apm/pinpoint · critical · BootStrapException

boot create failed. Error:

Error message

boot create failed. Error:

What it means

Inside AgentBootLoader's executeTemplate callable, after backing up system properties, the bootStrap class constructor (taking a Map) is invoked reflectively. If the class is abstract/interface or instantiation otherwise fails, an InstantiationException is rethrown as BootStrapException('boot create failed. Error: ...').

Source

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

    }

    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. Configure a concrete (non-abstract, non-interface) bootstrap class such as com.navercorp.pinpoint.profiler.DefaultAgent
2. Read the wrapped BootStrapException cause for the underlying instantiation problem and fix it
3. Ensure bootstrap and profiler jars are from the same Pinpoint release
4. Verify agentOption.toMap() supplies all values the boot constructor expects

Example fix

# before
-Dpinpoint.bootstrapclass=com.navercorp.pinpoint.profiler.AbstractAgent (abstract)
# after
-Dpinpoint.bootstrapclass=com.navercorp.pinpoint.profiler.DefaultAgent

Class<?> boot = Class.forName(bootClassName, true, loader);
if (Modifier.isAbstract(boot.getModifiers()) || boot.isInterface()) {
    throw new IllegalStateException("boot class must be concrete: " + bootClassName);
}
boot.getDeclaredConstructor(Map.class);

try {
    return bootLoader.boot(agentOption);
} catch (BootStrapException e) {
    if (e.getMessage().startsWith("boot create failed. Error:")) {
        logger.error("could not instantiate boot class " + bootClassName + "; check it is concrete and constructor args are valid; cause:", e.getCause());
    } else { throw e; }
}

When it happens

Trigger: Boot class is abstract or an interface so newInstance fails; getDeclaredConstructor(Map.class) succeeded but construction threw due to bad agentOption map contents (only for InstantiationException path).

Common situations: Pointing bootstrap config at an abstract base Agent class instead of a concrete implementation; version mismatch producing a constructor that cannot instantiate; agent option map missing keys the concrete constructor requires leading to early failure paths.

Related errors

• Invalid AgentClass:
• 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/7a31590a457d307c. Report an issue: GitHub.