{"record":{"id":"5ccfc2b615f11f8d","repo":"apache/beam","slug":"union-value-index-index-not-in-range-0-max","errorCode":null,"errorMessage":"union value index ${index} not in range [0..${max}]","messagePattern":"union value index (.+?) not in range \\[0\\.\\.(.+?)\\]","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/join/UnionCoder.java","lineNumber":52,"sourceCode":"})\npublic class UnionCoder extends StructuredCoder<RawUnionValue> {\n  // TODO: Think about how to integrate this with a schema object (i.e.\n  // a tuple of tuple tags).\n  /**\n   * Builds a union coder with the given list of element coders. This list corresponds to a mapping\n   * of union tag to Coder. Union tags start at 0.\n   */\n  public static UnionCoder of(List<Coder<?>> elementCoders) {\n    return new UnionCoder(elementCoders);\n  }\n\n  private int getIndexForEncoding(RawUnionValue union) {\n    if (union == null) {\n      throw new IllegalArgumentException(\"cannot encode a null tagged union\");\n    }\n    int index = union.getUnionTag();\n    if (index < 0 || index >= elementCoders.size()) {\n      throw new IllegalArgumentException(\n          \"union value index \" + index + \" not in range [0..\" + (elementCoders.size() - 1) + \"]\");\n    }\n    return index;\n  }\n\n  @Override\n  public void encode(RawUnionValue union, OutputStream outStream)\n      throws IOException, CoderException {\n    encode(union, outStream, Context.NESTED);\n  }\n\n  @SuppressWarnings(\"unchecked\")\n  @Override\n  public void encode(RawUnionValue union, OutputStream outStream, Context context)\n      throws IOException, CoderException {\n    int index = getIndexForEncoding(union);\n    // Write out the union tag.\n    VarInt.encode(index, outStream);","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/join/UnionCoder.java#L34-L70","documentation":"UnionCoder uses the tag (index) of a RawUnionValue to select one of its element coders. This error is thrown when the tag is negative or >= the number of registered element coders, so no matching coder exists for encoding.","triggerScenarios":"Encoding a RawUnionValue whose getUnionTag() was not obtained from the same UnionCoder instance — a hand-built tag, a stale tag after reordering the coder list, or a tag from a different union coder.","commonSituations":"Manually constructing RawUnionValue with an out-of-range int; the element coder list changed between pipeline construction and execution; a runner reshuffles values carrying tags that exceed the union size.","solutions":["Only create tags via unionCoder.getUnionTagForValue(value); never hardcode index ints.","Verify the tag is within [0, elementCoders.size()-1] before encoding.","Ensure the same UnionCoder instance and coder ordering are used in every stage that encodes/decodes the union."],"exampleFix":"// before\nnew RawUnionValue(7, value);\n// after\nUnionCoder coder = UnionCoder.of(elementCoders);\nint tag = coder.getUnionTagForValue(value); // guaranteed in range\nnew RawUnionValue(tag, value);","handlingStrategy":"validation","validationCode":"int tag = rawValue.getUnionTag();\nif (tag < 0 || tag >= elementCoders.size()) {\n  throw new IllegalArgumentException(\"union tag out of range: \" + tag);\n}","typeGuard":"boolean tagInRange(RawUnionValue v, int coderCount) {\n  return v != null && v.getUnionTag() >= 0 && v.getUnionTag() < coderCount;\n}","tryCatchPattern":null,"preventionTips":["Always derive tags from unionCoder.getUnionTagForValue(...), never hardcode indices.","Keep the element coder list ordering stable across pipeline stages; update tags together when reordering.","Share a single UnionCoder definition (constant) across producers and consumers."],"tags":["java","apache-beam","coder","index-out-of-range","serialization"],"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"}