apache/hadoop · error · HadoopIllegalArgumentException

Invalid values: dfs.bytes-per-checksum (={}) must divide cel

Error message

Invalid values: dfs.bytes-per-checksum (={}) must divide cell size (={}).

What it means

When a write to an erasure-coded file starts, DFSStripedOutputStream builds CellBuffers — per-block data and parity cell buffers with checksum arrays. Its constructor requires that dfs.bytes-per-checksum divides the EC policy's cell size evenly (cellSize % bytesPerChecksum == 0), because checksums are laid out per cell chunk. A violation throws HadoopIllegalArgumentException naming both values. The check runs in the DFSStripedOutputStream constructor, i.e., at FileSystem.create()/append() time, before any bytes are written.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DFSStripedOutputStream.java:212

      assert !updateStreamerMap.containsKey(streamer);
      updateStreamerMap.put(streamer, success);
    }

    void clearFailureStates() {
      newBlocks.clear();
      updateStreamerMap.clear();
      streamerUpdateResult.clear();
    }
  }

  /** Buffers for writing the data and parity cells of a stripe. */
  class CellBuffers {
    private final ByteBuffer[] buffers;
    private final byte[][] checksumArrays;

    CellBuffers(int numParityBlocks) {
      if (cellSize % bytesPerChecksum != 0) {
        throw new HadoopIllegalArgumentException("Invalid values: "
            + HdfsClientConfigKeys.DFS_BYTES_PER_CHECKSUM_KEY + " (="
            + bytesPerChecksum + ") must divide cell size (=" + cellSize + ").");
      }

      checksumArrays = new byte[numParityBlocks][];
      final int size = getChecksumSize() * (cellSize / bytesPerChecksum);
      for (int i = 0; i < checksumArrays.length; i++) {
        checksumArrays[i] = new byte[size];
      }

      buffers = new ByteBuffer[numAllBlocks];
      for (int i = 0; i < buffers.length; i++) {
        buffers[i] = BUFFER_POOL.getBuffer(useDirectBuffer(), cellSize);
        buffers[i].limit(cellSize);
      }
    }

    private ByteBuffer[] getBuffers() {

View on GitHub (pinned to 2add963021)

Solutions

Set dfs.bytes-per-checksum back to the default 512 (or any divisor of the policy's cell size, e.g., 1024).
Or choose/define the EC policy so its cell size is a multiple of the configured checksum size.
Pre-validate in code: erasureCodingPolicy.getCellSize() % conf.getLong(DFS_BYTES_PER_CHECKSUM_KEY, 512) == 0 before creating the output stream.
Remember the Configuration is read when the FileSystem/DFSClient is created — apply the fix and recreate the client/FileSystem rather than mutating conf of a cached instance.

Example fix

<!-- before: client core-site.xml -->
<property><name>dfs.bytes-per-checksum</name><value>1000</value></property>

<!-- after -->
<property><name>dfs.bytes-per-checksum</name><value>512</value></property>

Defensive patterns

Strategy: validation

Validate before calling

ErasureCodingPolicy ecPolicy =
    fs.getClient().getErasureCodingPolicy(new Path("/ec-dir"));
if (ecPolicy != null) {
  long bytesPerChecksum =
      conf.getLong(DFSConfigKeys.DFS_BYTES_PER_CHECKSUM_KEY,
                   DFSConfigKeys.DFS_BYTES_PER_CHECKSUM_DEFAULT);
  if (ecPolicy.getCellSize() % bytesPerChecksum != 0) {
    throw new IllegalStateException("dfs.bytes-per-checksum (" + bytesPerChecksum
        + ") must divide EC cell size (" + ecPolicy.getCellSize() + ")");
  }
}

Try / catch

try (FSDataOutputStream out = fs.create(path)) {
  ...
} catch (HadoopIllegalArgumentException e) {
  // config mismatch: fix dfs.bytes-per-checksum or the EC policy, then retry
}

Prevention

Keep dfs.bytes-per-checksum at the default 512 unless you also verify divisibility with every EC policy in use.
Add a startup config check that validates the divisibility invariant for all dir-level EC policies the app writes to.
Remember this validation uses the CLIENT's configuration — test with the same core-site.xml the app ships.

When it happens

Trigger: Creating or appending an EC-coded file while dfs.bytes-per-checksum (client config, default 512) does not divide the policy cell size — e.g., RS-6-3-1024k (cell 1048576) with dfs.bytes-per-checksum=1000. All stock policies use cell sizes that are multiples of 1024, so default or power-of-two checksum sizes never trip this.

Common situations: Tuning dfs.bytes-per-checksum to non-power-of-two values carried over from another system; custom EC policies with odd cell sizes; client-side core-site.xml or Configuration.setLong diverging from cluster defaults (this validation uses the client's configuration).

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

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