apache/druid · warning · java.lang.UnsupportedOperationException

Unmapping is not supported on this platform, because…

Error message

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

What it means

ByteBufferUtils.lookupUnmapMethodHandle resolves sun.misc.Unsafe.invokeCleaner via reflection to unmap direct ByteBuffers. On a JVM whose internal APIs do not provide this method (or block reflective access to it), it wraps the failure in this UnsupportedOperationException. Memory-mapped buffer unmapping is therefore unavailable on the current platform/JDK.

Solutions

Run on a supported OpenJDK/HotSpot build where sun.misc.Unsafe.invokeCleaner exists (JDK 9+ standard builds).
If your code calls unmap, guard with try/catch on UnsupportedOperationException and rely on GC to reclaim buffers.
Check --add-opens java.base/jdk.internal.misc and similar JVM flags if module access is the blocker, or switch JVM vendor.

Example fix

// before
ByteBufferUtils.unmap(mappedBuffer);
// after
try {
  ByteBufferUtils.unmap(mappedBuffer);
} catch (UnsupportedOperationException e) {
  // platform cannot unmap explicitly; buffer reclaimed by GC
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
  ByteBufferUtils.unmap(buffer);
} catch (UnsupportedOperationException e) {
  // platform cannot unmap; rely on GC
}

Prevention

Use standard HotSpot OpenJDK builds
Avoid stripping or locking down sun.misc.Unsafe access
Make unmap best-effort in your code paths

When it happens

Trigger: Calling ByteBufferUtils unmap methods (e.g. on mapped MappedByteBuffers) on a JDK lacking Unsafe.invokeCleaner, or a JDK where reflection into sun.misc.Unsafe is denied (module restrictions, non-HotSpot JVMs like J9/openj9 historically, exotic JDK builds).

Common situations: Running Druid on a non-standard JVM or a very new/locked-down JDK where sun.misc.Unsafe access is restricted; container images with unusual Java distributions; calling unmapping helpers in custom extensions on such JVMs.

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/aa2e04c6d95921c7. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/java/util/common/ByteBufferUtils.java:97

    }
    catch (Throwable throwable) {
      throw new RuntimeException("Unable to unmap the mapped buffer", throwable);
    }
  }

  private static MethodHandle lookupUnmapMethodHandle()
  {
    final MethodHandles.Lookup lookup = MethodHandles.lookup();
    try {
      MethodHandle unmapper = lookup.findVirtual(
          UnsafeUtils.theUnsafeClass(),
          "invokeCleaner",
          MethodType.methodType(void.class, ByteBuffer.class)
      );
      return unmapper.bindTo(UnsafeUtils.theUnsafe());
    }
    catch (ReflectiveOperationException | RuntimeException e1) {
      throw new UnsupportedOperationException("Unmapping is not supported on this platform, because internal " +
                                              "Java APIs are not compatible with this Druid version", e1);
    }
  }

  /**
   * Same as {@link ByteBuffer#allocateDirect(int)}, but returns a closeable {@link ResourceHolder} that
   * frees the buffer upon close.
   *
   * Direct (off-heap) buffers are an alternative to on-heap buffers that allow memory to be managed
   * outside the purview of the garbage collector. It's most useful when allocating big chunks of memory,
   * like processing buffers.
   *
   * Holders cannot be closed more than once. Attempting to close a holder twice will earn you an
   * {@link IllegalStateException}.
   */
  public static ResourceHolder<ByteBuffer> allocateDirect(final int size)
  {
    class DirectByteBufferHolder implements ResourceHolder<ByteBuffer>

View on GitHub (pinned to 9b90983fd2)