apache/hadoop · error · UnsupportedOperationException

${className} does not support enhanced byte buffer access.

Error message

${className} does not support enhanced byte buffer access.

What it means

After its seek housekeeping, read(ByteBufferPool, maxLength, opts) requires the wrapped stream to implement HasEnhancedByteBufferAccess, the marker interface for pooled/zero-copy ByteBuffer reads. Any other wrapped stream type gets UnsupportedOperationException ('does not support enhanced byte buffer access') naming the class.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/crypto/CryptoInputStream.java:722

    return result;
  }

  @Override
  public ByteBuffer read(ByteBufferPool bufferPool, int maxLength,
      EnumSet<ReadOption> opts) throws IOException,
      UnsupportedOperationException {
    checkStream();
    if (outBuffer.remaining() > 0) {
      if (!(in instanceof Seekable)) {
        throw new UnsupportedOperationException(in.getClass().getCanonicalName()
            + " does not support seek.");
      }
      // Have some decrypted data unread, need to reset.
      ((Seekable) in).seek(getPos());
      resetStreamOffset(getPos());
    }
    if (!(in instanceof HasEnhancedByteBufferAccess)) {
      throw new UnsupportedOperationException(in.getClass().getCanonicalName()
          + " does not support enhanced byte buffer access.");
    }
    final ByteBuffer buffer = ((HasEnhancedByteBufferAccess) in).
        read(bufferPool, maxLength, opts);
    if (buffer != null) {
      final int n = buffer.remaining();
      if (n > 0) {
        streamOffset += buffer.remaining(); // Read n bytes
        final int pos = buffer.position();
        decrypt(buffer, n, pos);
      }
    }
    return buffer;
  }

  @Override
  public void releaseBuffer(ByteBuffer buffer) {
    if (!(in instanceof HasEnhancedByteBufferAccess)) {

View on GitHub (pinned to 2add963021)

Solutions

Use plain read(byte[]) for encrypted streams; zero-copy is generally unavailable through the crypto layer
Check the underlying filesystem's zero-copy support before enabling such code paths for encrypted data
Catch UnsupportedOperationException and fall back to buffered reads

Example fix

// before
ByteBuffer zeroCopy = fsIn.read(bufferPool, maxLen, opts); // UOE without HasEnhancedByteBufferAccess

// after
try {
  ByteBuffer zeroCopy = fsIn.read(bufferPool, maxLen, opts);
} catch (UnsupportedOperationException e) {
  byte[] buf = new byte[maxLen];
  int n = fsIn.read(buf, 0, maxLen); // buffered fallback
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
  ByteBuffer b = fsIn.read(bufferPool, maxLen, opts);
} catch (UnsupportedOperationException e) {
  byte[] buf = new byte[maxLen];
  int n = fsIn.read(buf, 0, maxLen); // buffered fallback
}

Prevention

Disable zero-copy read paths for files inside encryption zones
Add a capability probe (one guarded call at open time) and cache the result per stream
Keep a single fallback utility mapping zero-copy misses to plain byte[] reads

When it happens

Trigger: Calling the ByteBufferPool read API on a CryptoInputStream whose inner stream does not implement HasEnhancedByteBufferAccess — non-HDFS filesystems, wrapped local streams, or older HDFS clients without zero-copy support.

Common situations: Applications relying on zero-copy (direct-buffer) reads — columnar engines, mappers using elastiscale read paths — on encrypted files or on filesystem clients without zero-copy streams.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/b282623b318c0090. Report an issue: GitHub.