apache/beam · error · IllegalArgumentException

union value index not in range [0.. ]

Error message

union value index ${index} not in range [0..${max}]

What it means

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.

Solutions

1. Only create tags via unionCoder.getUnionTagForValue(value); never hardcode index ints.
2. Verify the tag is within [0, elementCoders.size()-1] before encoding.
3. Ensure the same UnionCoder instance and coder ordering are used in every stage that encodes/decodes the union.

Example fix

// before
new RawUnionValue(7, value);
// after
UnionCoder coder = UnionCoder.of(elementCoders);
int tag = coder.getUnionTagForValue(value); // guaranteed in range
new RawUnionValue(tag, value);

int tag = rawValue.getUnionTag();
if (tag < 0 || tag >= elementCoders.size()) {
  throw new IllegalArgumentException("union tag out of range: " + tag);
}

boolean tagInRange(RawUnionValue v, int coderCount) {
  return v != null && v.getUnionTag() >= 0 && v.getUnionTag() < coderCount;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• cannot encode a null BitSet
• cannot encode a null byte[]
• cannot encode a null Integer
• cannot encode a null Long
• cannot encode a null Short

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/5ccfc2b615f11f8d. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/join/UnionCoder.java:52

})
public class UnionCoder extends StructuredCoder<RawUnionValue> {
  // TODO: Think about how to integrate this with a schema object (i.e.
  // a tuple of tuple tags).
  /**
   * Builds a union coder with the given list of element coders. This list corresponds to a mapping
   * of union tag to Coder. Union tags start at 0.
   */
  public static UnionCoder of(List<Coder<?>> elementCoders) {
    return new UnionCoder(elementCoders);
  }

  private int getIndexForEncoding(RawUnionValue union) {
    if (union == null) {
      throw new IllegalArgumentException("cannot encode a null tagged union");
    }
    int index = union.getUnionTag();
    if (index < 0 || index >= elementCoders.size()) {
      throw new IllegalArgumentException(
          "union value index " + index + " not in range [0.." + (elementCoders.size() - 1) + "]");
    }
    return index;
  }

  @Override
  public void encode(RawUnionValue union, OutputStream outStream)
      throws IOException, CoderException {
    encode(union, outStream, Context.NESTED);
  }

  @SuppressWarnings("unchecked")
  @Override
  public void encode(RawUnionValue union, OutputStream outStream, Context context)
      throws IOException, CoderException {
    int index = getIndexForEncoding(union);
    // Write out the union tag.
    VarInt.encode(index, outStream);

View on GitHub (pinned to 12126d8942)