{"record":{"id":"b3003eb586e977da","repo":"apache/beam","slug":"union-tag-uniontag-has-no-corresponding-tuple-tag-in-the","errorCode":null,"errorMessage":"union tag ${unionTag} has no corresponding tuple tag in the result schema","messagePattern":"union tag (.+?) has no corresponding tuple tag in the result schema","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/join/CoGbkResult.java","lineNumber":121,"sourceCode":"      valuesByTag.add(new ArrayList<>());\n    }\n\n    // Demultiplex the first imMemoryElementCount tagged union values\n    // according to their tag.\n    final Iterator<RawUnionValue> taggedIter = taggedValues.iterator();\n    int elementCount = 0;\n    while (taggedIter.hasNext()) {\n      if (elementCount++ >= inMemoryElementCount) {\n        // Let the tails be lazy.\n        largeKeyCount.inc();\n        break;\n      }\n      RawUnionValue value = taggedIter.next();\n      // Make sure the given union tag has a corresponding tuple tag in the\n      // schema.\n      int unionTag = value.getUnionTag();\n      if (schema.size() <= unionTag) {\n        throw new IllegalStateException(\n            \"union tag \" + unionTag + \" has no corresponding tuple tag in the result schema\");\n      }\n      valuesByTag.get(unionTag).add(value.getValue());\n    }\n\n    if (!taggedIter.hasNext()) {\n      // Everything fits into memory, just store it.\n      valueMap = (List) valuesByTag;\n      return;\n    }\n\n    // If we get here, there were more elements than we can afford to\n    // keep in memory, so we copy the re-iterable of remaining items\n    // and append filtered views to each of the sorted lists computed earlier.\n    LOG.info(\n        \"CoGbkResult has more than {} elements, reiteration (which may be slow) is required.\",\n        inMemoryElementCount);\n    valueMap = new ArrayList<>();","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/join/CoGbkResult.java#L103-L139","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure all RawUnionValue inputs belong to PCollections included in the CoGbkResultSchema.","Rebuild the schema with CoGbkResultSchema.of(...) including every input TupleTag.","Fix runner/encoder code that reorders or drops union values, shifting tag indices."],"exampleFix":"// before\nschema = CoGbkResultSchema.of(Structs.of(\"tag1\", tag1)); // 1 tag\n// union value with tag 1 (second input) arrives -> throw\n// after\nschema = CoGbkResultSchema.of(Structs.of(\"tag1\", tag1, \"tag2\", tag2)); // include all inputs","handlingStrategy":"validation","validationCode":"// Before building CoGbkResult, verify every input's tag index:\nfor (RawUnionValue v : unionValues) {\n  if (v.getUnionTag() >= schema.size())\n    throw new IllegalArgumentException(\"Union tag \" + v.getUnionTag() + \" exceeds schema\");\n}","typeGuard":"null","tryCatchPattern":"try {\n  CoGbkResult result = new CoGbkResult(schema, taggedIter);\n} catch (IllegalStateException e) {\n  throw new IllegalStateException(\"Union values do not match CoGbkResultSchema; check join inputs\", e);\n}","preventionTips":["Build schemas with CoGbkResultSchema.of() covering all input TupleTags","Never reuse union-tagged PCollections across different co-groups","Verify custom runner/encoder code preserves union tag indices"],"tags":["java","apache-beam","co-group","join","internal-invariant"],"backgroundTag":"index-out-of-range","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}