pinpoint-apm/pinpoint · critical · BootStrapException

boot class not found. bootClass: Error:

Error message

boot class not found. bootClass: Error:

What it means

AgentBootLoader.getBootStrapClass calls this.classLoader.loadClass(clazzName) to load the Pinpoint boot class (default com.navercorp.pinpoint.profiler.DefaultAgent or configured bootClass). If the class cannot be found on the boot classloader path, a BootStrapException 'boot class not found. bootClass:... Error:' is thrown and agent boot aborts.

Source

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

                    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. Check the bootClass configuration (profiler.bootclass or the default) for typos and confirm the class exists in the shipped jars
2. Verify the agent installation: pinpoint-bootstrap and pinpoint-profiler jars are present and on the -javaagent / boot path
3. Confirm bootstrap and profiler module versions match — do not mix jars from different Pinpoint releases
4. If a custom boot class is used, ensure it is packaged into the jar the boot classloader reads

String name = bootClassName.replace('.', '/') + ".class";
if (bootClassLoader.getResource(name) == null) {
    throw new IllegalStateException("Boot class resource missing on boot classpath: " + name);
}

When it happens

Trigger: loadClass throwing ClassNotFoundException for the configured bootClass name — wrong -Dprofiler.bootclass value, or the pinpoint bootstrap/profiler jar is missing from the boot classloader's search path.

Common situations: Typos in the bootClass system property; incomplete agent installation where pinpoint-profiler or bootstrap jars were not placed on the bootstrap path; shading/repackaging the agent and dropping the DefaultAgent class; version mismatch between bootstrap and profiler jars.

Related errors

• boot method invoke failed. Error:
• Invalid pinpoint-bootstrap.jar:
• J9BootLoader create fail Caused by:
• initialize fail Caused by:
• invoke fail Caused by:

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