What causes "Not support enhanced byte buffer access." in apache/hadoop?

Use the plain byte[] APIs (read(byte[], off, len), readFully) for erasure-coded files.

apache/hadoop · error · UnsupportedOperationException

Not support enhanced byte buffer access.

Error message

Not support enhanced byte buffer access.

What it means

DFSStripedInputStream deliberately does not implement enhanced (zero-copy) byte-buffer reads: read(ByteBufferPool, int, EnumSet<ReadOption>) unconditionally throws UnsupportedOperationException. Erasure-coded reads may need online read recovery — reconstructing missing cells from data plus parity — which cannot honor zero-copy semantics, so the capability is disabled for striped streams rather than returning wrong data.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DFSStripedInputStream.java:569

        DFSClient.LOG.warn(Arrays.toString(nodes) + " are unavailable and " +
            "all striping blocks on them are lost. " +
            "IgnoredNodes = {}", ignoredNodes);
        warnedNodes.addAll(dnUUIDs);
      }
    } else {
      super.reportLostBlock(lostBlock, ignoredNodes);
    }
  }

  /**
   * May need online read recovery, zero-copy read doesn't make
   * sense, so don't support it.
   */
  @Override
  public synchronized ByteBuffer read(ByteBufferPool bufferPool,
      int maxLength, EnumSet<ReadOption> opts)
          throws IOException, UnsupportedOperationException {
    throw new UnsupportedOperationException(
        "Not support enhanced byte buffer access.");
  }

  @Override
  public synchronized void releaseBuffer(ByteBuffer buffer) {
    throw new UnsupportedOperationException(
        "Not support enhanced byte buffer access.");
  }

  @Override
  public synchronized void unbuffer() {
    super.unbuffer();
    if (curStripeBuf != null) {
      BUFFER_POOL.putBuffer(curStripeBuf);
      curStripeBuf = null;
    }
    if (parityBuf != null) {
      BUFFER_POOL.putBuffer(parityBuf);

View on GitHub (pinned to 2add963021)

Solutions

Use the plain byte[] APIs (read(byte[], off, len), readFully) for erasure-coded files.
Branch up front: if the wrapped stream is a DFSStripedInputStream (or the file's EC policy is non-null), skip the ByteBufferPool path.
Catch UnsupportedOperationException at the call site and fall back to byte[] reads.
Upgrade the consuming library to a version with EC-aware read paths (e.g., newer HBase releases detect EC and avoid pooled reads).

Example fix

// before
ByteBuffer buf = in.read(bufferPool, maxLen,
    EnumSet.of(ReadOption.SKIP_CHECKSUMS)); // throws on EC files

// after
if (in.getWrappedStream() instanceof DFSStripedInputStream) {
  byte[] b = new byte[maxLen];
  int n = in.read(b, 0, maxLen); // regular path, always supported
} else {
  ByteBuffer buf = in.read(bufferPool, maxLen,
      EnumSet.of(ReadOption.SKIP_CHECKSUMS));
}

Defensive patterns

Strategy: fallback

Validate before calling

ErasureCodingPolicy ecPolicy =
    fs.getClient().getErasureCodingPolicy(stat.getPath());
if (ecPolicy != null) {
  // erasure-coded: pooled zero-copy read is not offered; use byte[] read
}
// or check via file status replication == 0 marker for EC files
if (stat.getReplication() == 0) { /* EC file: use read(byte[]) */ }

Type guard

boolean striped =
    in.getWrappedStream() instanceof org.apache.hadoop.hdfs.DFSStripedInputStream;
if (striped) {
  // skip read(ByteBufferPool, ...) / releaseBuffer(...): they throw
  // UnsupportedOperationException on erasure-coded files
}

Try / catch

ByteBuffer buf = null;
try {
  buf = in.read(bufferPool, maxLen, opts);
} catch (UnsupportedOperationException e) {
  // zero-copy unsupported (e.g., EC file) -> plain read path
  byte[] b = new byte[maxLen];
  int n = in.read(b, 0, maxLen);
} finally {
  if (buf != null) in.releaseBuffer(buf);
}

Prevention

Before adopting zero-copy reads, check the file's storage policy: EC files never support read(ByteBufferPool, ...).
Wrap pooled-read usage so an UnsupportedOperationException silently degrades to byte[] reads.
When testing against EC datasets, add explicit cases for the pooled-read API so regressions surface early.

When it happens

Trigger: Calling FSDataInputStream.read(bufferPool, maxLength, opts) — the ByteBufferPool/zero-copy path used by high-throughput consumers such as HBase — on a stream opened from a file stored with an erasure-coding policy (e.g., RS-6-3-1024k).

Common situations: Migrating datasets or HBase-like workloads to EC policies and reusing zero-copy reader code that worked on replicated files; libraries that probe for enhanced byte-buffer support; enabling SKIP_CHECKSUMS/drop-behind options through the pooled-read API.

Related errors

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