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

Use seek() plus sequential readFully when the stream is Seekable

apache/hadoop · error · UnsupportedOperationException

${className} does not support positioned readFully.

Error message

${className} does not support positioned readFully.

What it means

The byte[] positioned readFully on CryptoInputStream requires `in instanceof PositionedReadable`. If the wrapped stream supports only sequential reads, UnsupportedOperationException naming the wrapped class is thrown up front, before any decryption happens.

Source

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

        } finally {
          localPadding = afterDecryption(localDecryptor, localInBuffer,
                                         filePosition + length, localIV);
        }
      }
    } finally {
      returnBuffer(localInBuffer);
      returnBuffer(localOutBuffer);
      returnDecryptor(localDecryptor);
    }
  }

  /** Positioned read fully. It is thread-safe */
  @Override
  public void readFully(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 readFully.");
    }
    ((PositionedReadable) in).readFully(position, buffer, offset, length);
    if (length > 0) {
      // This operation does not change the current offset of the file
      decrypt(position, buffer, offset, length);
    }
  }

  @Override
  public void readFully(long position, byte[] buffer) throws IOException {
    readFully(position, buffer, 0, buffer.length);
  }

  /** Seek to a position. */
  @Override
  public void seek(long pos) throws IOException {
    if (pos < 0) {

View on GitHub (pinned to 2add963021)

Solutions

Use seek() plus sequential readFully when the stream is Seekable
Wrap the source stream in a PositionedReadable implementation before building the CryptoInputStream
Catch UnsupportedOperationException and use a sequential copy strategy

Example fix

// before
cryptoIn.readFully(pos, buf, 0, len); // UOE without PositionedReadable

// after
try {
  cryptoIn.readFully(pos, buf, 0, len);
} catch (UnsupportedOperationException e) {
  cryptoIn.seek(pos);
  IOUtils.readFully(cryptoIn, buf, 0, len);
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
  in.readFully(pos, buf, off, len);
} catch (UnsupportedOperationException e) {
  in.seek(pos);
  IOUtils.readFully(in, buf, off, len);
}

Prevention

Do not assume FSDataInputStream positional APIs work on every FileSystem; probe once per filesystem type and cache the result
Prefer seek+sequential reads in reader loops that already track a current offset
For custom streams, implement PositionedReadable so wrapped/encrypted views inherit the capability

When it happens

Trigger: readFully(position, buffer, offset, length) on a CryptoInputStream wrapping a non-PositionedReadable stream — e.g. wrapped local streams, some connector streams, or mocks.

Common situations: Split-based record readers doing positional readFully on encrypted files backed by incompatible stream types; libraries assuming every FSDataInputStream supports positional reads.

Related errors

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