{"record":{"id":"28a4be1d0384dcd7","repo":"pinpoint-apm/pinpoint","slug":"define-fail-cl-caused-by-28a4be","errorCode":null,"errorMessage":"{} define fail cl:{} Caused by:{}","messagePattern":"(.+?) define fail cl:(.+?) Caused by:(.+?)","errorType":"console","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/ReflectionDefineClass.java","lineNumber":59,"sourceCode":"\n    @Override\n    public Class<?> defineClass(ClassLoader classLoader, String name, byte[] bytes) {\n        if (logger.isDebugEnabled()) {\n            logger.debug(\"define class:{} cl:{}\", name, classLoader);\n        }\n        try {\n            return (Class<?>) DEFINE_CLASS.invoke(classLoader, name, bytes, 0, bytes.length);\n        } catch (InvocationTargetException e) {\n            // unwrap: the message of the LinkageError/ClassFormatError thrown by the VM is on the cause\n            final Throwable cause = e.getCause() != null ? e.getCause() : e;\n            throw handleDefineClassFail(classLoader, name, cause);\n        } catch (ReflectiveOperationException e) {\n            throw handleDefineClassFail(classLoader, name, e);\n        }\n    }\n\n    private RuntimeException handleDefineClassFail(ClassLoader classLoader, String className, Throwable cause) {\n        logger.warn(\"{} define fail cl:{} Caused by:{}\", className, classLoader, cause.getMessage(), cause);\n        return new RuntimeException(className + \" define fail Caused by:\" + cause.getMessage(), cause);\n    }\n\n\n}\n","sourceCodeStart":41,"sourceCodeEnd":65,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/ReflectionDefineClass.java#L41-L65","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the 'Caused by' message to find the real cause (ClassFormatError vs LinkageError vs duplicate definition)","Check whether another interceptor/plugin transforms the same class (duplicate define in same classloader)","Verify instrumented bytecode targets a class file version compatible with the JVM","Exclude the offending class via profiler config if the transformation cannot be fixed","Upgrade Pinpoint agent version to get the bytecode fix"],"exampleFix":"// before\nthrow handleDefineClassFail(classLoader, name, e);\n// after\nlogger.error(\"define fail cl:{} name:{}\", classLoader, name, e); // inspect root cause, then fix transformation or exclude class","handlingStrategy":"try-catch","validationCode":"// before attaching/starting the agent, verify the class is not already defined in the loader\nboolean alreadyDefined;\ntry { Class.forName(name, false, classLoader); alreadyDefined = true; }\ncatch (ClassNotFoundException e) { alreadyDefined = false; }","typeGuard":null,"tryCatchPattern":"try {\n    agent.start(...);\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"define fail\")) {\n        logger.warn(\"Pinpoint failed to define class; check Caused by and exclude the class\", e);\n    } else { throw e; }\n}","preventionTips":["Read the 'Caused by' chain, not the wrapper message","Avoid running multiple bytecode agents that transform the same class","Keep agent version compatible with the target JVM","Exclude problematic classes from instrumentation via profiler config"],"tags":["classloading","instrumentation","reflection","jvm"],"backgroundTag":"class-not-found","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}