{"record":{"id":"03dd6a34e4c4db1d","repo":"pinpoint-apm/pinpoint","slug":"classname-define-fail-caused-by-causemessage","errorCode":null,"errorMessage":"${className} define fail Caused by:${causeMessage}","messagePattern":"(.+?) define fail Caused by:(.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/ReflectionDefineClass.java","lineNumber":52,"sourceCode":"        try {\n            DEFINE_CLASS = ClassLoader.class.getDeclaredMethod(\"defineClass\", String.class, byte[].class, int.class, int.class);\n            DEFINE_CLASS.setAccessible(true);\n        } catch (ReflectiveOperationException e) {\n            throw new IllegalStateException(\"Cannot access ClassLoader.defineClass(String, byte[], int, int)\", e);\n        }\n    }\n\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":34,"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#L34-L65","documentation":"ReflectionDefineClass.defineClass uses reflection on ClassLoader.defineClass to inject instrumented bytecode into the target JVM. When the VM rejects the class (InvocationTargetException wrapping a LinkageError/ClassFormatError) or the reflective call itself fails, handleDefineClassFail wraps the cause in a RuntimeException '<className> define fail Caused by:<causeMessage>'.","triggerScenarios":"DEFINE_CLASS.invoke(classLoader, name, bytes, 0, bytes.length) throws: the VM rejects the transformed bytecode (ClassFormatError, LinkageError, duplicate class definition), or the reflective Method invocation fails (ReflectiveOperationException).","commonSituations":"A bytecode transform plugin produced invalid bytecode for that class; the class was already defined by the same loader (duplicate define); Java module system (JPMS) blocks defining into a restricted loader; Pinpoint agent version incompatible with the target JVM version.","solutions":["Read the Caused-by chain: fix the underlying ClassFormatError/LinkageError (usually a faulty transform plugin).","Disable the Pinpoint plugin/transformer producing the bad bytecode via profiling config to isolate the culprit.","Check JVM/Pinpoint agent version compatibility (e.g. unsafe/reflection define restrictions on JDK 11+).","Exclude the failing class from instrumentation via the profiler's exclude options."],"exampleFix":"// before (agent config)\nprofiler.instrument.classloading=reflection\n// after (fall back for JPMS/JDK11+)\nprofiler.instrument.classloading=unsafe","handlingStrategy":"try-catch","validationCode":"// JVM-side guard before agent startup\nString javaSpec = System.getProperty(\"java.specification.version\");\nif (Double.parseDouble(javaSpec) >= 11) {\n  // prefer non-reflective define path / verified agent build\n}","typeGuard":null,"tryCatchPattern":"try {\n    Class<?> c = reflectionDefineClass.defineClass(classLoader, name, bytes);\n} catch (RuntimeException e) {\n    logger.warn(\"define failed for {} : {}\", name, e.getCause(), e);\n    // fall back to excluding the class from instrumentation\n}","preventionTips":["Test plugins with -verify bytecode before deploying the agent.","Keep the agent build matched to the target JDK.","Maintain an instrumentation exclude list for fragile classes.","Always inspect the cause chain, not the wrapper message."],"tags":["java","bytecode","instrumentation","classloader"],"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"}