{"record":{"id":"09bd037310466e9b","repo":"apache/beam","slug":"illegal-shard-number-shardnum","errorCode":null,"errorMessage":"Illegal shard number: {shardNum}","messagePattern":"Illegal shard number: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/ShardingWritableByteChannel.java","lineNumber":80,"sourceCode":"   *\n   * @return The total number of bytes written. If the shard number is {@link #ALL_SHARDS}, then the\n   *     total is the sum of each individual shard write.\n   */\n  public int writeToShard(int shardNum, ByteBuffer src) throws IOException {\n    if (shardNum >= 0) {\n      return writers.get(shardNum).write(src);\n    }\n\n    switch (shardNum) {\n      case ALL_SHARDS:\n        int size = 0;\n        for (WritableByteChannel writer : writers) {\n          size += writer.write(src);\n        }\n        return size;\n\n      default:\n        throw new IllegalArgumentException(\"Illegal shard number: \" + shardNum);\n    }\n  }\n\n  /**\n   * Writes a buffer to all shards.\n   *\n   * <p>Same as calling {@code writeToShard(ALL_SHARDS, buf)}.\n   */\n  @Override\n  public int write(ByteBuffer src) throws IOException {\n    return writeToShard(ALL_SHARDS, src);\n  }\n\n  @Override\n  public boolean isOpen() {\n    for (WritableByteChannel writer : writers) {\n      if (!writer.isOpen()) {\n        return false;","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/ShardingWritableByteChannel.java#L62-L98","documentation":"ShardingWritableByteChannel.write dispatches writes to one of a fixed set of shard writers based on the shard number; if shardNum falls outside the configured shard range it throws this IllegalArgumentException. It indicates an internal dispatch failure — the caller attempted to write to a shard that does not exist.","triggerScenarios":"Calling write(ByteBuffer) on a channel whose computed target shard number (from the shard-modulo logic or explicitly set shardNum) is negative or >= number of writers; only reachable via a misconfigured sharding setup or internal bug in writeToShard.","commonSituations":"File-based sinks writing sharded outputs where shard count configuration is inconsistent (e.g. numShards changed between channel construction and write), or custom code subclassing/invoking writeToShard with an out-of-range shard index.","solutions":["Ensure the shard number is computed as a valid index: 0 <= shardNum < number of open shard writers.","Verify the channel was constructed/configured with the same numShards used when selecting the shard.","If subclassing or calling writeToShard directly, clamp or validate shardNum before dispatching.","Report as a bug if it arises from standard Beam file sinks with a consistent shard configuration."],"exampleFix":"// before\nchannel.writeToShard(shardNum, buffer); // shardNum may exceed writers\n// after\nif (shardNum < 0 || shardNum >= writers.size()) {\n  throw new IllegalArgumentException(\"shardNum=\" + shardNum + \" outside 0..\" + (writers.size() - 1));\n}\nchannel.writeToShard(shardNum, buffer);","handlingStrategy":"validation","validationCode":"if (shardNum < 0 || shardNum >= numShards) {\n  throw new IllegalArgumentException(\"shardNum \" + shardNum + \" must be in [0, \" + numShards + \")\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  channel.writeToShard(shardNum, buffer);\n} catch (IllegalArgumentException e) {\n  // correct shard selection or re-init channel\n}","preventionTips":["Compute shard indexes with Math.floorMod(value, numShards) to avoid negatives.","Keep shard count configuration consistent between channel creation and write paths.","Never call writeToShard directly unless you control the shard index space."],"tags":["beam","io","sharding","index-out-of-range"],"backgroundTag":"value-out-of-range","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}