pinpoint-apm/pinpoint · error · RuntimeException

{} define fail cl:{} Caused by:{}

Error message

{} define fail cl:{} Caused by:{}

What it means

Thrown by ReflectionDefineClass.handleDefineClassFail when defining (loading) a transformed class via reflection into the target ClassLoader fails. Pinpoint wraps the underlying ReflectiveOperationException (e.g. ClassFormatError, LinkageError, SecurityException) into a RuntimeException carrying the class name, classloader, and cause message. It indicates bytecode injection produced a class the JVM refused to define in that classloader.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/ReflectionDefineClass.java:59

    @Override
    public Class<?> defineClass(ClassLoader classLoader, String name, byte[] bytes) {
        if (logger.isDebugEnabled()) {
            logger.debug("define class:{} cl:{}", name, classLoader);
        }
        try {
            return (Class<?>) DEFINE_CLASS.invoke(classLoader, name, bytes, 0, bytes.length);
        } catch (InvocationTargetException e) {
            // unwrap: the message of the LinkageError/ClassFormatError thrown by the VM is on the cause
            final Throwable cause = e.getCause() != null ? e.getCause() : e;
            throw handleDefineClassFail(classLoader, name, cause);
        } catch (ReflectiveOperationException e) {
            throw handleDefineClassFail(classLoader, name, e);
        }
    }

    private RuntimeException handleDefineClassFail(ClassLoader classLoader, String className, Throwable cause) {
        logger.warn("{} define fail cl:{} Caused by:{}", className, classLoader, cause.getMessage(), cause);
        return new RuntimeException(className + " define fail Caused by:" + cause.getMessage(), cause);
    }


}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Read the 'Caused by' message to find the real cause (ClassFormatError vs LinkageError vs duplicate definition)
2. Check whether another interceptor/plugin transforms the same class (duplicate define in same classloader)
3. Verify instrumented bytecode targets a class file version compatible with the JVM
4. Exclude the offending class via profiler config if the transformation cannot be fixed
5. Upgrade Pinpoint agent version to get the bytecode fix

Example fix

// before
throw handleDefineClassFail(classLoader, name, e);
// after
logger.error("define fail cl:{} name:{}", classLoader, name, e); // inspect root cause, then fix transformation or exclude class

// before attaching/starting the agent, verify the class is not already defined in the loader
boolean alreadyDefined;
try { Class.forName(name, false, classLoader); alreadyDefined = true; }
catch (ClassNotFoundException e) { alreadyDefined = false; }

try {
    agent.start(...);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("define fail")) {
        logger.warn("Pinpoint failed to define class; check Caused by and exclude the class", e);
    } else { throw e; }
}

When it happens

Trigger: ReflectionDefineClass.defineClass is invoked during instrumentation and the reflective define (locating defineClass via reflection and invoking it) throws a ReflectiveOperationException, or the JVM rejects the bytecode (duplicate class definition in the same classloader, incompatible class file version, bytecode transformation bug, missing references).

Common situations: Agent attaches to an app whose bytecode transformation produced invalid bytecode; the same class is defined twice in one classloader; instrumented class references another class not visible to that classloader; JDK version upgrade changes class file constraints; SecurityManager restricts defineClass via reflection.

Related errors

• {} define fail cl:{} Caused by:{}
• ${name} define fail Caused by:${e.getMessage()}
• invocation fail, className=
• not found 'set' method, className=
• ${after} method not found. ${Arrays.toString(afterParamList)

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