{"record":{"id":"f60d7fb05d0aca81","repo":"pinpoint-apm/pinpoint","slug":"cannot-access-sun-misc-unsafe-defineclass","errorCode":null,"errorMessage":"Cannot access sun.misc.Unsafe.defineClass","messagePattern":"Cannot access sun\\.misc\\.Unsafe\\.defineClass","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/UnsafeDefineClass.java","lineNumber":48,"sourceCode":" * resolved reflectively and must not be reached on JDK 9+.\n */\nfinal class UnsafeDefineClass implements DefineClass {\n\n    private final Logger logger = LogManager.getLogger(this.getClass());\n\n    private static final Object UNSAFE;\n    private static final Method DEFINE_CLASS;\n\n    static {\n        try {\n            final Class<?> unsafeClass = Class.forName(\"sun.misc.Unsafe\");\n            final Field theUnsafe = unsafeClass.getDeclaredField(\"theUnsafe\");\n            theUnsafe.setAccessible(true);\n            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    }","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/UnsafeDefineClass.java#L30-L66","documentation":"IllegalStateException raised in UnsafeDefineClass's static initializer when reflective access to sun.misc.Unsafe.defineClass fails. Pinpoint uses Unsafe.defineClass to inject classes into arbitrary classloaders; this API is inaccessible on JDKs where sun.misc.Unsafe internals are encapsulated or removed.","triggerScenarios":"Class initialization of UnsafeDefineClass on a JVM where theUnsafe field or defineClass(String, byte[], int, int, ClassLoader, ProtectionDomain) cannot be resolved via reflection - typically JDK 9+ with strong encapsulation, or a JVM without sun.misc.Unsafe.","commonSituations":"Running the Pinpoint agent on JDK 9/11/17+ where --add-exports/--add-opens for jdk.unsupported is not set, running on a non-HotSpot JVM, or using a hardened JVM that blocks sun.misc.Unsafe reflection.","solutions":["Use a Pinpoint agent version that supports your JDK (newer versions use MethodHandles/Lookup.defineClass instead of Unsafe).","Add JVM flags: --add-opens java.base/jdk.internal.misc=ALL-UNNAMED and appropriate --add-exports for jdk.unsupported.","Run on JDK 8 where sun.misc.Unsafe.defineClass is accessible if you must use an old agent version.","Check the wrapped ReflectiveOperationException cause to see whether theUnsafe or defineClass is the missing member."],"exampleFix":"// before (JDK 17, no flags)\njava -jar pinpoint-bootstrap.jar ...\n// after\njava --add-opens java.base/java.lang=ALL-UNNAMED --add-exports jdk.unsupported/sun.misc=ALL-UNNAMED -jar pinpoint-bootstrap.jar ...","handlingStrategy":"validation","validationCode":"// verify accessibility at startup\ntry {\n  Class<?> u = Class.forName(\"sun.misc.Unsafe\");\n  Field f = u.getDeclaredField(\"theUnsafe\"); f.setAccessible(true);\n} catch (Throwable t) { /* Unsafe path unavailable: use --add-opens or upgrade agent */ }","typeGuard":null,"tryCatchPattern":"try { UnsafeDefineClass h = new UnsafeDefineClass(); } catch (IllegalStateException e) { logger.error(\"Unsafe.defineClass unavailable on this JVM; upgrade agent or add --add-opens flags\", e); }","preventionTips":["Match the agent version to the target JDK","Add --add-opens/--add-exports for jdk.unsupported on JDK 9+","Test agent startup on each supported JDK in CI"],"tags":["jdk","unsafe","reflection","compatibility","pinpoint"],"backgroundTag":"deprecated-api-usage","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}