apache/beam · error · IllegalArgumentException

TupleTag ${tag} corresponds to an empty result, and no defau

Error message

TupleTag ${tag} corresponds to an empty result, and no default was provided

What it means

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.

Source

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

  private CoGbkResult(CoGbkResultSchema schema, List<Iterable<?>> valueMap) {
    this.schema = schema;
    this.valueMap = valueMap;
  }

  private @Nullable <V> V innerGetOnly(
      TupleTag<V> tag, @Nullable V defaultValue, boolean useDefault) {
    int index = schema.getIndex(tag);
    if (index < 0) {
      throw new IllegalArgumentException("TupleTag " + tag + " is not in the schema");
    }
    @SuppressWarnings("unchecked")
    Iterator<V> unions = (Iterator<V>) valueMap.get(index).iterator();
    if (!unions.hasNext()) {
      if (useDefault) {
        return defaultValue;
      } else {
        throw new IllegalArgumentException(
            "TupleTag " + tag + " corresponds to an empty result, and no default was provided");
      }
    }
    V value = unions.next();
    if (unions.hasNext()) {
      throw new IllegalArgumentException(
          "TupleTag " + tag + " corresponds to a non-singleton result");
    }
    return value;
  }

  /**
   * A re-iterable that notifies an observer at every advance, and upon finishing, but only once
   * across all copies.
   *
   * @param <T> The value type of the underlying iterable.
   */
  private static class ObservingReiterator<T> implements Reiterator<T> {

View on GitHub (pinned to 12126d8942)

Solutions

1. Use getOnly(tag, defaultValue) to supply a fallback
2. Use get(tag) which returns an empty iterable checkable via isEmpty()
3. Use getAll(tag) and handle the empty case explicitly

Example fix

// before
V v = result.getOnly(tag); // throws when empty
// after
V v = result.getOnly(tag, null);
if (v != null) { /* handle */ }

boolean empty = result.getAll(tag).iterator().hasNext() == false;

try { return result.getOnly(tag); } catch (IllegalArgumentException e) { return defaultValue; }

When it happens

Trigger: Calling getOnly(tag) (no default) on a CoGbkResult where the given key had no records for that PCollection in the CoGroupByKey.

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

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• TupleTag ${tag} corresponds to a non-singleton result
• Attempting to call and() on a CoGbkResult apparently not cre
• Unknown context parameter: ${param.parDoParamName}
• Unsupported window mapping fn: ${sideInput.windowMappingFn.u
• Unimplemented access pattern: ${accessPattern}

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