{"record":{"id":"9bc064e1cd840d61","repo":"apache/druid","slug":"define-class-not-supported-exception","errorCode":"DEFINE_CLASS_NOT_SUPPORTED_EXCEPTION","errorMessage":"defineClass is not supported on this platform, because internal Java APIs are not compatible with this Druid version","messagePattern":"defineClass is not supported on this platform, because internal Java APIs are not compatible with this Druid version","errorType":"exception","errorClass":"java.lang.UnsupportedOperationException","httpStatus":null,"severity":"critical","filePath":"processing/src/main/java/org/apache/druid/java/util/common/DefineClassUtils.java","lineNumber":96,"sourceCode":"    privateLookupIn = MethodHandles.insertArguments(privateLookupIn, 1, lookup);\n\n    // defineClass = (Class targetClass, byte[] byteCode) -> privateLookupIn(targetClass).defineClass(byteCode)\n    defineClass = MethodHandles.filterArguments(defineClass, 0, privateLookupIn);\n\n    // add a dummy String argument to match the corresponding JDK8 version\n    // defineClass = (Class targetClass, byte[] byteCode, String className) -> defineClass(targetClass, byteCode)\n    defineClass = MethodHandles.dropArguments(defineClass, 2, String.class);\n    return defineClass;\n  }\n\n  public static Class defineClass(\n      Class<?> targetClass,\n      byte[] byteCode,\n      String className\n  )\n  {\n    if (DEFINE_CLASS == null) {\n      throw new UnsupportedOperationException(\n          \"defineClass is not supported on this platform, \"\n          + \"because internal Java APIs are not compatible with this Druid version\",\n          DEFINE_CLASS_NOT_SUPPORTED_EXCEPTION\n      );\n    }\n\n    try {\n      return (Class) DEFINE_CLASS.invokeExact(targetClass, byteCode, className);\n    }\n    catch (Throwable t) {\n      throw new UnsupportedOperationException(\"Unable to define specialized class: \" + className, t);\n    }\n  }\n}\n","sourceCodeStart":78,"sourceCodeEnd":111,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/java/util/common/DefineClassUtils.java#L78-L111","documentation":"Druid's DefineClassUtils uses the internal JDK MethodHandles.Lookup.defineClass (or sun.misc.Unsafe.defineClass) API to define expression/Guice-specialized classes at runtime. On platforms where the internal API handle cannot be resolved (typically newer JDKs where the API was encapsulated or removed), DEFINE_CLASS is null and this UnsupportedOperationException is thrown instead of silently failing.","triggerScenarios":"Calling DefineClassUtils.defineClass(targetClass, byteCode, className) on a JVM where the internal defineClass method handle could not be resolved, e.g. running on an unsupported/newer Java version not validated by Druid.","commonSituations":"Running Druid on a JDK version outside its supported range (e.g. JDK 16+ where strong encapsulation blocks internal APIs), or exotic JVMs (GraalVM native image, alternative vendors) lacking the internal API.","solutions":["Run Druid on a supported JDK version listed in the Druid docs for your release","Remove or disable features that rely on runtime class definition (e.g. certain expression specializations) via configuration","If using GraalVM native image, add reachability metadata / native-image substitutions or avoid this code path","File/consult an issue to confirm platform support for your JVM vendor and version"],"exampleFix":"// before (stack trace originates from defineClass call)\nClass<?> cls = DefineClassUtils.defineClass(targetClass, byteCode, className);\n// after\nclassMethod = DefineClassUtils.isDefineClassSupported()\n    ? DefineClassUtils.defineClass(targetClass, byteCode, className)\n    : fallbackInterpreterPath();","handlingStrategy":"try-catch","validationCode":"if (!DefineClassUtils.isDefineClassSupported()) {\n  // take non-specialized code path\n}","typeGuard":"boolean canDefineClass = DefineClassUtils.isDefineClassSupported();","tryCatchPattern":"try {\n  return DefineClassUtils.defineClass(targetClass, byteCode, className);\n} catch (UnsupportedOperationException e) {\n  log.warn(e, \"defineClass unavailable on %s; falling back\", System.getProperty(\"java.vm.name\"));\n  return fallback;\n}","preventionTips":["Pin Druid to a JDK version on the supported matrix","Smoke-test startup on every new JDK/vendor before rollout","Avoid GraalVM native image for components needing runtime class definition","Monitor Druid release notes for internal-API dependency changes"],"tags":["unsupported-platform","jdk-compatibility","reflection"],"backgroundTag":"unsupported-platform","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}