pinpoint-apm/pinpoint · error · BootStrapException

execute fail. Error:

Error message

execute fail. Error:

What it means

ContextClassLoaderExecuteTemplate.execute runs a Callable with the thread's context classloader temporarily swapped to the given classloader, then restores it. Any non-BootStrapException thrown inside the block (including InvocationTargetException from the reflective boot-class instantiation in AgentBootLoader) is wrapped in a BootStrapException with the message 'execute fail. Error:'. BootStrapExceptions are rethrown unchanged.

Source

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

    public V execute(Callable<V> callable) throws BootStrapException {
        try {
            final Thread currentThread = Thread.currentThread();
            final ClassLoader before = currentThread.getContextClassLoader();
            // ctxCl == null safe?
            currentThread.setContextClassLoader(this.classLoader);
            try {
                return callable.call();
            } finally {
                // even though  the "BEFORE" classloader  is null, rollback  is needed.
                // if an exception occurs BEFORE callable.call(), the call flow can't reach here.
                // so  rollback  here is right.
                currentThread.setContextClassLoader(before);
            }
        } catch (BootStrapException ex){
            throw ex;
        } catch (Exception ex) {
            throw new BootStrapException("execute fail. Error:" + ex.getMessage(), ex);
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Read the wrapped 'Caused by' chain — the real failure is the original exception inside the execute block, not the wrapper
2. Fix the underlying cause reported by the cause (config value, missing class, constructor exception)
3. If InvocationTargetException is the cause, look at its target exception for the exception thrown by the boot class constructor
4. Validate the agentArgs map keys/values before boot so the constructor receives valid data

Example fix

// before
new ContextClassLoaderExecuteTemplate(bootClassLoader).execute(() -> { ... }); // opaque 'execute fail'
// after
try { ... } catch (BootStrapException e) {
    log.error("boot failed, root cause:", ExceptionUtils.getRootCause(e));
}

try {
    return execute(callable);
} catch (BootStrapException e) {
    throw e; // already classified
} catch (Exception e) {
    throw new BootStrapException("execute fail. Error:" + e.getMessage(), e);
}

When it happens

Trigger: Any exception other than BootStrapException escaping the executed callable — typically the reflective bootClass construction failing (IllegalArgumentException for bad constructor args, InvocationTargetException from a throwing constructor, ExceptionInInitializerError), or a bug in the callback itself.

Common situations: Malformed agentArgs map passed to the boot constructor; DefaultAgent static initializer or constructor throwing (bad config, plugin load failure); using the template with a classloader that fails to load classes referenced by the callback.

Related errors

• initialize fail Caused by:
• invoke fail Caused by:
• bootstrapClassLoader not found Caused by:
• boot method invoke failed. Error:
• Unable to set registry for ServiceTypeProvider

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