{"record":{"id":"6ee18b266100488d","repo":"pinpoint-apm/pinpoint","slug":"define-fail-cl-caused-by-6ee18b","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/UnsafeDefineClass.java","lineNumber":69,"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(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":51,"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#L51-L73","documentation":"Thrown by UnsafeDefineClass.handleDefineClassFail when defining a transformed class via sun.misc.Unsafe.defineClass fails. The underlying error (wrapped as ReflectiveOperationException, typically caused by ClassFormatError or LinkageError) is wrapped in a RuntimeException with the class name, classloader, and cause message. Functionally identical to the reflection-based define failure but on the Unsafe code path.","triggerScenarios":"UnsafeDefineClass.defineClass is invoked during instrumentation and the Unsafe-based define throws - e.g. invalid/incompatible bytecode, duplicate class in same classloader, missing referenced classes, or sun.misc.Unsafe unavailable/restricted (JDK 17+ encapsulation).","commonSituations":"Newer JDKs restrict sun.misc.Unsafe access; bytecode transformation bug; class defined twice in one loader; class file version newer than the JVM; missing dependency class at define time.","solutions":["Check the 'Caused by' for the actual LinkageError/ClassFormatError","Confirm the JDK supports the Unsafe path; on JDK 17+ add required --add-opens flags or upgrade Pinpoint which uses Lookup-based defines","Check for duplicate transformation of the same class in the same classloader","Exclude the problematic class or upgrade the agent for a bytecode fix"],"exampleFix":"// before\nthrow handleDefineClassFail(classLoader, name, e);\n// after\nif (e.getCause() instanceof LinkageError) {\n    logger.warn(\"class {} already defined or incompatible in cl:{}\", name, classLoader, e);\n}\nthrow handleDefineClassFail(classLoader, name, e);","handlingStrategy":"try-catch","validationCode":"// verify the JDK still exposes sun.misc.Unsafe define support before relying on this path\ntry {\n    Class.forName(\"sun.misc.Unsafe\");\n} catch (ClassNotFoundException e) {\n    // Unsafe unavailable; expect UnsafeDefineClass to fail, use alternative agent version\n}","typeGuard":null,"tryCatchPattern":"try {\n    agent.start(...);\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"define fail\")) {\n        logger.warn(\"Unsafe define failed; check Caused by for LinkageError\", e);\n    } else { throw e; }\n}","preventionTips":["On JDK 17+, ensure required --add-opens flags or use an agent version using Lookup.defineClass","Avoid duplicate class transformation in the same classloader","Confirm instrumented bytecode version is <= target JVM version","Inspect the 'Caused by' before changing any config"],"tags":["classloading","instrumentation","unsafe","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"}