{"record":{"id":"cc52b8420e26b5ad","repo":"pinpoint-apm/pinpoint","slug":"classname-define-fail-caused-by-causemessage-cc52b8","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/UnsafeDefineClass.java","lineNumber":62,"sourceCode":"            UNSAFE = theUnsafe.get(null);\n            DEFINE_CLASS = unsafeClass.getMethod(\"defineClass\",\n                    String.class, byte[].class, int.class, int.class, ClassLoader.class, ProtectionDomain.class);\n        } catch (ReflectiveOperationException e) {\n            throw new IllegalStateException(\"Cannot access sun.misc.Unsafe.defineClass\", 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(UNSAFE, name, bytes, 0, bytes.length, classLoader, null);\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","sourceCodeStart":44,"sourceCodeEnd":73,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/UnsafeDefineClass.java#L44-L73","documentation":"UnsafeDefineClass.defineClass uses sun.misc.Unsafe.defineClass to inject bytecode. As in ReflectionDefineClass, when the VM rejects the class or the Unsafe invocation fails, handleDefineClassFail throws RuntimeException '<className> define fail Caused by:<causeMessage>'.","triggerScenarios":"DEFINE_CLASS.invoke(UNSAFE, name, bytes, 0, bytes.length, classLoader, null) throws InvocationTargetException (VM rejected the class: ClassFormatError/LinkageError/duplicate define) or ReflectiveOperationException (Unsafe API missing/changed).","commonSituations":"Invalid transformed bytecode from a plugin; class already defined by the target loader; newer JDKs restricting/removing sun.misc.Unsafe.defineClass (JDK 11+ deprecation, removal paths); agent-JVM version mismatch.","solutions":["Read the cause message for the VM-level reason and fix the offending transformer.","Switch instrument classloading mode in Pinpoint config (e.g. to reflection/ASMFallback) if Unsafe is unavailable.","Exclude the failing class from instrumentation.","Upgrade the agent to a build supporting the running JDK."],"exampleFix":"// before\nreturn (Class<?>) DEFINE_CLASS.invoke(UNSAFE, name, bytes, 0, bytes.length, classLoader, null);\n// after (guard availability)\nif (!UNSAFE_SUPPORTED) {\n    return reflectionDefineClass.defineClass(classLoader, name, bytes);\n}","handlingStrategy":"fallback","validationCode":"// check Unsafe availability at agent init\nboolean unsafeOk;\ntry {\n    Class<?> u = Class.forName(\"sun.misc.Unsafe\");\n    unsafeOk = u.getDeclaredMethod(\"defineClass\", String.class, byte[].class, int.class, int.class, ClassLoader.class, java.security.ProtectionDomain.class) != null;\n} catch (ReflectiveOperationException e) {\n    unsafeOk = false;\n}","typeGuard":null,"tryCatchPattern":"try {\n    return unsafeDefineClass.defineClass(classLoader, name, bytes);\n} catch (RuntimeException e) {\n    logger.warn(\"Unsafe define failed for {} ({}), falling back\", name, e.getCause());\n    return reflectionDefineClass.defineClass(classLoader, name, bytes);\n}","preventionTips":["Detect sun.misc.Unsafe.defineClass availability at startup and select the define strategy then.","On JDK 9+ set --add-opens if reflective access is required.","Keep bytecode-transformed classes small and verified."],"tags":["java","bytecode","unsafe","instrumentation"],"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"}