apache/hadoop · error · IllegalArgumentException

Configured BlockReaderLocalLegacy buffer size ({}) is not la

Error message

Configured BlockReaderLocalLegacy buffer size ({}) is not large enough to hold a single chunk ({}). Please configure dfs.client.read.shortcircuit.buffer.size appropriately

What it means

The legacy short-circuit reader (BlockReaderLocalLegacy, used for local reads without a domain socket) sizes its read buffer in whole checksum chunks: getSlowReadBufferNumChunks throws IllegalArgumentException when dfs.client.read.shortcircuit.buffer.size (default 1 MiB) is smaller than the file's bytesPerChecksum, because the buffer could not hold even one chunk.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/impl/BlockReaderLocalLegacy.java:307

      // short-circuit read for all subsequent use in the ClientContext.  Unlike
      // the newer short-circuit read implementation, we have no communication
      // channel for the DataNode to notify the client that the path has been
      // invalidated.  Therefore, our only option is to skip caching.
      if (pathinfo != null && !storageType.isTransient()) {
        LOG.debug("Cached location of block {} as {}", blk, pathinfo);
        localDatanodeInfo.setBlockLocalPathInfo(blk, pathinfo);
      }
    } catch (IOException e) {
      localDatanodeInfo.resetDatanodeProxy(); // Reset proxy on error
      throw e;
    }
    return pathinfo;
  }

  private static int getSlowReadBufferNumChunks(int bufferSizeBytes,
      int bytesPerChecksum) {
    if (bufferSizeBytes < bytesPerChecksum) {
      throw new IllegalArgumentException("Configured BlockReaderLocalLegacy " +
          "buffer size (" + bufferSizeBytes + ") is not large enough to hold " +
          "a single chunk (" + bytesPerChecksum +  "). Please configure " +
          HdfsClientConfigKeys.Read.ShortCircuit.BUFFER_SIZE_KEY +
          " appropriately");
    }

    // Round down to nearest chunk size
    return bufferSizeBytes / bytesPerChecksum;
  }

  private BlockReaderLocalLegacy(ShortCircuitConf conf, String hdfsfile,
      ExtendedBlock block, long startOffset, FileInputStream dataIn)
      throws IOException {
    this(conf, hdfsfile, block, startOffset,
        DataChecksum.newDataChecksum(DataChecksum.Type.NULL, 4), false,
        dataIn, startOffset, null);
  }

View on GitHub (pinned to 2add963021)

Solutions

Restore or raise dfs.client.read.shortcircuit.buffer.size to at least the largest bytesPerChecksum in use; keeping the 1 MiB default is simplest.
Check the file's checksum layout (how it was created) to learn its bytesPerChecksum.
Prefer the modern short-circuit path (configure dfs.domain.socket.path), which does not use this legacy buffer math.

Example fix

# before
<property><name>dfs.client.read.shortcircuit.buffer.size</name><value>256</value></property>

# after: at least bytesPerChecksum; 1 MiB default is safe
<property><name>dfs.client.read.shortcircuit.buffer.size</name><value>1048576</value></property>

Defensive patterns

Strategy: validation

Validate before calling

int buf = conf.getInt("dfs.client.read.shortcircuit.buffer.size",
    1024 * 1024);
int bpc = conf.getInt("dfs.bytes-per-checksum", 512);
Preconditions.checkArgument(buf >= bpc,
    "dfs.client.read.shortcircuit.buffer.size (%s) must be >= "
    + "bytesPerChecksum (%s)", buf, bpc);

Prevention

Fail fast on this config invariant at client startup, not on first read.
Do not shrink dfs.client.read.shortcircuit.buffer.size — the 1 MiB default covers normal chunk sizes.
When files are created with non-default bytesPerChecksum, verify every reader's buffer size covers it.

When it happens

Trigger: Reading a file whose bytes-per-checksum exceeds dfs.client.read.shortcircuit.buffer.size — the buffer was tuned down (e.g., 256 bytes) while the file uses default or larger chunks, or files written with a large per-file bytesPerChecksum are read by clients with a shrunken buffer.

Common situations: Operators lower dfs.client.read.shortcircuit.buffer.size believing it is a small I/O buffer (it is a chunk buffer, default 1048576); mixed clusters where files created with non-default checksum settings are read by all clients.

Related errors

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