apache/hadoop · error · UnsupportedOperationException

${className} does not support positioned reads with byte buf

Error message

${className} does not support positioned reads with byte buffers.

What it means

CryptoInputStream.read(long, ByteBuffer) is the ByteBuffer-variant positioned read; it requires the wrapped stream to implement ByteBufferPositionedReadable. If `in` does not, UnsupportedOperationException with the wrapped class name is thrown after checkStream() passes.

Source

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

    final int n = ((PositionedReadable) in).read(position, buffer, offset,
        length);
    if (n > 0) {
      // This operation does not change the current offset of the file
      decrypt(position, buffer, offset, n);
    }

    return n;
  }

  /**
   * Positioned read using {@link ByteBuffer}s. This method is thread-safe.
   */
  @Override
  public int read(long position, final ByteBuffer buf)
      throws IOException {
    checkStream();
    if (!(in instanceof ByteBufferPositionedReadable)) {
      throw new UnsupportedOperationException(in.getClass().getCanonicalName()
          + " does not support positioned reads with byte buffers.");
    }
    int bufPos = buf.position();
    final int n = ((ByteBufferPositionedReadable) in).read(position, buf);
    if (n > 0) {
      // This operation does not change the current offset of the file
      decrypt(position, buf, n, bufPos);
    }

    return n;
  }

  /**
   * Positioned readFully using {@link ByteBuffer}s. This method is thread-safe.
   */
  @Override
  public void readFully(long position, final ByteBuffer buf)
      throws IOException {

View on GitHub (pinned to 2add963021)

Solutions

Switch to the byte[] positioned variant read(position, bytes, off, len), which only requires PositionedReadable
Fall back to plain sequential read() when positioning is not essential
Upgrade the filesystem client so its streams implement ByteBufferPositionedReadable

Example fix

// before
int n = cryptoIn.read(pos, byteBuffer); // UOE without ByteBufferPositionedReadable

// after
byte[] tmp = new byte[byteBuffer.remaining()];
int n = cryptoIn.read(pos, tmp, 0, tmp.length);
if (n > 0) { byteBuffer.put(tmp, 0, n); }

Defensive patterns

Strategy: try-catch

Try / catch

try {
  n = in.read(pos, byteBuffer);
} catch (UnsupportedOperationException e) {
  // ByteBufferPositionedReadable missing: use the byte[] positioned variant
  byte[] tmp = new byte[byteBuffer.remaining()];
  n = in.read(pos, tmp, 0, tmp.length);
  if (n > 0) byteBuffer.put(tmp, 0, n);
}

Prevention

Prefer the byte[] positioned APIs; treat ByteBuffer positioned reads as an optimization only
Gate ByteBuffer-based read paths on filesystem client versions that implement ByteBufferPositionedReadable
Keep a single fallback helper for ByteBuffer vs byte[] read dispatch

When it happens

Trigger: Calling read(position, buf) where the inner stream implements only PositionedReadable (byte[] variant) or neither — typical of filesystem clients predating ByteBufferPositionedReadable.

Common situations: Zero-copy/ByteBuffer-oriented readers (query engines, modern parquet readers) hitting encrypted files; mixing a newer client API with older connector stream implementations.

Related errors

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