apache/druid · critical · java.lang.UnsupportedOperationException

DEFINE_CLASS_NOT_SUPPORTED_EXCEPTION

DEFINE_CLASS_NOT_SUPPORTED_EXCEPTION

Error message

defineClass is not supported on this platform, because internal Java APIs are not compatible with this Druid version

What it means

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.

Solutions

  1. Run Druid on a supported JDK version listed in the Druid docs for your release
  2. Remove or disable features that rely on runtime class definition (e.g. certain expression specializations) via configuration
  3. If using GraalVM native image, add reachability metadata / native-image substitutions or avoid this code path
  4. File/consult an issue to confirm platform support for your JVM vendor and version

Example fix

// before (stack trace originates from defineClass call)
Class<?> cls = DefineClassUtils.defineClass(targetClass, byteCode, className);
// after
classMethod = DefineClassUtils.isDefineClassSupported()
    ? DefineClassUtils.defineClass(targetClass, byteCode, className)
    : fallbackInterpreterPath();
Defensive patterns

Strategy: try-catch

Validate before calling

if (!DefineClassUtils.isDefineClassSupported()) {
  // take non-specialized code path
}

Type guard

boolean canDefineClass = DefineClassUtils.isDefineClassSupported();

Try / catch

try {
  return DefineClassUtils.defineClass(targetClass, byteCode, className);
} catch (UnsupportedOperationException e) {
  log.warn(e, "defineClass unavailable on %s; falling back", System.getProperty("java.vm.name"));
  return fallback;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/9bc064e1cd840d61. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/java/util/common/DefineClassUtils.java:96

    privateLookupIn = MethodHandles.insertArguments(privateLookupIn, 1, lookup);

    // defineClass = (Class targetClass, byte[] byteCode) -> privateLookupIn(targetClass).defineClass(byteCode)
    defineClass = MethodHandles.filterArguments(defineClass, 0, privateLookupIn);

    // add a dummy String argument to match the corresponding JDK8 version
    // defineClass = (Class targetClass, byte[] byteCode, String className) -> defineClass(targetClass, byteCode)
    defineClass = MethodHandles.dropArguments(defineClass, 2, String.class);
    return defineClass;
  }

  public static Class defineClass(
      Class<?> targetClass,
      byte[] byteCode,
      String className
  )
  {
    if (DEFINE_CLASS == null) {
      throw new UnsupportedOperationException(
          "defineClass is not supported on this platform, "
          + "because internal Java APIs are not compatible with this Druid version",
          DEFINE_CLASS_NOT_SUPPORTED_EXCEPTION
      );
    }

    try {
      return (Class) DEFINE_CLASS.invokeExact(targetClass, byteCode, className);
    }
    catch (Throwable t) {
      throw new UnsupportedOperationException("Unable to define specialized class: " + className, t);
    }
  }
}

View on GitHub (pinned to 9b90983fd2)