apache/beam · error · IllegalStateException

union tag ${unionTag} has no corresponding tuple tag in the

Error message

union tag ${unionTag} has no corresponding tuple tag in the result schema

What it means

CoGbkResult's constructor throws IllegalStateException when an incoming RawUnionValue's union tag is >= the size of the CoGbkResultSchema. Each tag in a CoGroupByKey schema corresponds to one input PCollection; a larger tag means a union value from a PCollection that is not part of this co-group result — an internal consistency violation in the join graph.

Source

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

      valuesByTag.add(new ArrayList<>());
    }

    // Demultiplex the first imMemoryElementCount tagged union values
    // according to their tag.
    final Iterator<RawUnionValue> taggedIter = taggedValues.iterator();
    int elementCount = 0;
    while (taggedIter.hasNext()) {
      if (elementCount++ >= inMemoryElementCount) {
        // Let the tails be lazy.
        largeKeyCount.inc();
        break;
      }
      RawUnionValue value = taggedIter.next();
      // Make sure the given union tag has a corresponding tuple tag in the
      // schema.
      int unionTag = value.getUnionTag();
      if (schema.size() <= unionTag) {
        throw new IllegalStateException(
            "union tag " + unionTag + " has no corresponding tuple tag in the result schema");
      }
      valuesByTag.get(unionTag).add(value.getValue());
    }

    if (!taggedIter.hasNext()) {
      // Everything fits into memory, just store it.
      valueMap = (List) valuesByTag;
      return;
    }

    // If we get here, there were more elements than we can afford to
    // keep in memory, so we copy the re-iterable of remaining items
    // and append filtered views to each of the sorted lists computed earlier.
    LOG.info(
        "CoGbkResult has more than {} elements, reiteration (which may be slow) is required.",
        inMemoryElementCount);
    valueMap = new ArrayList<>();

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure all RawUnionValue inputs belong to PCollections included in the CoGbkResultSchema.
2. Rebuild the schema with CoGbkResultSchema.of(...) including every input TupleTag.
3. Fix runner/encoder code that reorders or drops union values, shifting tag indices.

Example fix

// before
schema = CoGbkResultSchema.of(Structs.of("tag1", tag1)); // 1 tag
// union value with tag 1 (second input) arrives -> throw
// after
schema = CoGbkResultSchema.of(Structs.of("tag1", tag1, "tag2", tag2)); // include all inputs

// Before building CoGbkResult, verify every input's tag index:
for (RawUnionValue v : unionValues) {
  if (v.getUnionTag() >= schema.size())
    throw new IllegalArgumentException("Union tag " + v.getUnionTag() + " exceeds schema");
}

null

try {
  CoGbkResult result = new CoGbkResult(schema, taggedIter);
} catch (IllegalStateException e) {
  throw new IllegalStateException("Union values do not match CoGbkResultSchema; check join inputs", e);
}

When it happens

Trigger: Building a CoGbkResult from a KV of a CoGbkResultSchema and an Iterable<RawUnionValue> where a union value carries a tag index beyond schema.size() — e.g. mismatched schemas between the CoGroupByKey transform and its inputs, or custom code mixing union values across joins.

Common situations: Hand-constructing CoGbkResult or KeyedWorkList items in tests/custom runners; reusing union-tagged outputs from one CoGroupByKey as input to another with a smaller schema; runner bugs in encoding/decoding union values.

Related errors

• No fields were set for input ${tag}
• The input PCollectionTuple has tags: ${inputTags} and the jo
• Cannot set both a global and per-tag fields.
• TupleTag ${tag} is not in the schema
• Unexpected join type

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