{"record":{"id":"cdd2739a0cd741b7","repo":"apache/beam","slug":"tupletag-tag-corresponds-to-an-empty-result-and-no-default","errorCode":null,"errorMessage":"TupleTag ${tag} corresponds to an empty result, and no default was provided","messagePattern":"TupleTag (.+?) corresponds to an empty result, and no default was provided","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/join/CoGbkResult.java","lineNumber":403,"sourceCode":"\n  private CoGbkResult(CoGbkResultSchema schema, List<Iterable<?>> valueMap) {\n    this.schema = schema;\n    this.valueMap = valueMap;\n  }\n\n  private @Nullable <V> V innerGetOnly(\n      TupleTag<V> tag, @Nullable V defaultValue, boolean useDefault) {\n    int index = schema.getIndex(tag);\n    if (index < 0) {\n      throw new IllegalArgumentException(\"TupleTag \" + tag + \" is not in the schema\");\n    }\n    @SuppressWarnings(\"unchecked\")\n    Iterator<V> unions = (Iterator<V>) valueMap.get(index).iterator();\n    if (!unions.hasNext()) {\n      if (useDefault) {\n        return defaultValue;\n      } else {\n        throw new IllegalArgumentException(\n            \"TupleTag \" + tag + \" corresponds to an empty result, and no default was provided\");\n      }\n    }\n    V value = unions.next();\n    if (unions.hasNext()) {\n      throw new IllegalArgumentException(\n          \"TupleTag \" + tag + \" corresponds to a non-singleton result\");\n    }\n    return value;\n  }\n\n  /**\n   * A re-iterable that notifies an observer at every advance, and upon finishing, but only once\n   * across all copies.\n   *\n   * @param <T> The value type of the underlying iterable.\n   */\n  private static class ObservingReiterator<T> implements Reiterator<T> {","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/join/CoGbkResult.java#L385-L421","documentation":"getOnly() returns exactly one element per key for the given TupleTag. When the iterable for that tag is empty for this key and no default value was supplied, the method throws instead of returning null.","triggerScenarios":"Calling getOnly(tag) (no default) on a CoGbkResult where the given key had no records for that PCollection in the CoGroupByKey.","commonSituations":"Outer-join-like access patterns where keys may be missing from one side; user code assuming every side has data for every key after CoGroupByKey.","solutions":["Use getOnly(tag, defaultValue) to supply a fallback","Use get(tag) which returns an empty iterable checkable via isEmpty()","Use getAll(tag) and handle the empty case explicitly"],"exampleFix":"// before\nV v = result.getOnly(tag); // throws when empty\n// after\nV v = result.getOnly(tag, null);\nif (v != null) { /* handle */ }","handlingStrategy":"fallback","validationCode":"boolean empty = result.getAll(tag).iterator().hasNext() == false;","typeGuard":null,"tryCatchPattern":"try { return result.getOnly(tag); } catch (IllegalArgumentException e) { return defaultValue; }","preventionTips":["Always pass a default value when keys may be missing on one side","Use get(tag) and check emptiness before getOnly","Document per-key cardinality expectations of join inputs"],"tags":["beam","cogbkresult","empty-result","getonly"],"backgroundTag":"empty-result-set","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"}