What causes "${className} does not support positioned read." in apache/hadoop?

Use sequential read() plus seek-based navigation instead of positional reads on encrypted files

apache/hadoop · error · UnsupportedOperationException

${className} does not support positioned read.

Error message

${className} does not support positioned read.

What it means

CryptoInputStream decrypts on the fly by wrapping another InputStream, and can only offer positioned reads if the wrapped stream implements PositionedReadable. read(long, byte[], int, int) checks `in instanceof PositionedReadable` and throws UnsupportedOperationException naming the wrapped class before any I/O when that interface is missing.

Source

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

  @Override
  public synchronized void close() throws IOException {
    if (closed) {
      return;
    }
    
    super.close();
    freeBuffers();
    codec.close();
    closed = true;
  }
  
  /** Positioned read. It is thread-safe */
  @Override
  public int read(long position, byte[] buffer, int offset, int length)
      throws IOException {
    checkStream();
    if (!(in instanceof PositionedReadable)) {
      throw new UnsupportedOperationException(in.getClass().getCanonicalName()
          + " does not support positioned read.");
    }
    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 {

View on GitHub (pinned to 2add963021)

Solutions

Use sequential read() plus seek-based navigation instead of positional reads on encrypted files
If you control the source stream, wrap it in a PositionedReadable implementation before constructing the CryptoInputStream
Catch UnsupportedOperationException and fall back to seek + sequential read

Example fix

// before
int n = cryptoIn.read(pos, buf, 0, len); // UOE if inner stream lacks PositionedReadable

// after
try {
  int n = cryptoIn.read(pos, buf, 0, len);
} catch (UnsupportedOperationException e) {
  cryptoIn.seek(pos);
  IOUtils.readFully(cryptoIn, buf, 0, len); // sequential fallback
}

Defensive patterns

Strategy: try-catch

Validate before calling

// CryptoInputStream implements PositionedReadable itself, so instanceof cannot
// narrow the inner stream. Pre-check the encryption context instead:
// EncryptionZone ez = hdfsAdmin.getEncryptionZoneForPath(path);
// if (ez != null) use sequential reads only for this path.

Try / catch

try {
  n = in.read(pos, buf, off, len);
} catch (UnsupportedOperationException e) {
  // inner stream lacks PositionedReadable: sequential fallback
  in.seek(pos);
  n = in.read(buf, off, len);
}

Prevention

Avoid positional reads on files inside encryption zones unless the underlying client streams are known to implement PositionedReadable
Centralize stream capability fallbacks (positional -> seek+read) in one helper used by all readers
In tests, wrap mock streams with PositionedReadable to match production stream types

When it happens

Trigger: Calling read(position, buffer, offset, length) (directly or via FSDataInputStream positional APIs) on a CryptoInputStream whose inner stream is a plain sequential InputStream — raw local streams, some object-store/wrapped connector streams, or mock streams in tests.

Common situations: Reading files in HDFS encryption zones with client libraries that rely on positional reads (parquet/orc style split readers); unit tests wrapping arbitrary streams with CryptoInputStream.

Related errors

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