apache/beam · error · IllegalArgumentException

TupleTag ${tag} is not in the schema

Error message

TupleTag ${tag} is not in the schema

What it means

CoGbkResult.getAll(TupleTag) throws IllegalArgumentException when the requested tag was not part of the original CoGroupByKey schema. getIndex returns -1 for unknown tags, and Beam converts that into this explicit error so callers know they are asking for an output that this co-group never produced.

Source

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

    return schema;
  }

  @Override
  public String toString() {
    return valueMap.toString();
  }

  /**
   * Returns the values from the table represented by the given {@code TupleTag<V>} as an {@code
   * Iterable<V>} (which may be empty if there are no results).
   *
   * <p>If tag was not part of the original {@link CoGroupByKey}, throws an
   * IllegalArgumentException.
   */
  public <V> Iterable<V> getAll(TupleTag<V> tag) {
    int index = schema.getIndex(tag);
    if (index < 0) {
      throw new IllegalArgumentException("TupleTag " + tag + " is not in the schema");
    }
    @SuppressWarnings("unchecked")
    Iterable<V> unions = (Iterable<V>) valueMap.get(index);
    return unions;
  }

  /** Like {@link #getAll(TupleTag)} but using a String instead of a {@link TupleTag}. */
  public <V> Iterable<V> getAll(String tag) {
    return getAll(new TupleTag<>(tag));
  }

  /**
   * If there is a singleton value for the given tag, returns it. Otherwise, throws an
   * IllegalArgumentException.
   *
   * <p>If tag was not part of the original {@link CoGroupByKey}, throws an
   * IllegalArgumentException.
   */

View on GitHub (pinned to 12126d8942)

Solutions

1. Request a tag that was passed into the same CoGroupByKey call.
2. Reuse the same TupleTag constants (shared static finals) in both the co-group and getAll/getOnly calls.
3. Add the missing TupleTag to the CoGroupByKey input tuple if it should be present.

Example fix

// before
TupleTag<Integer> resultsTag = new TupleTag<>(); // fresh identity, not in schema
result.getAll(resultsTag);
// after
private static final TupleTag<Integer> RESULTS_TAG = new TupleTag<Integer>() {};
// pass RESULTS_TAG to CoGroupByKey, then:
result.getAll(RESULTS_TAG);

// Confirm the tag exists before calling getAll:
int idx = result.getSchema().getIndex(tag);
if (idx < 0) { throw new IllegalArgumentException("Tag " + tag + " not in co-group"); }

<V> boolean tagInSchema(CoGbkResult r, TupleTag<V> tag) {
  return r.getSchema().getIndex(tag) >= 0;
}

try {
  Iterable<V> vals = result.getAll(tag);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Use a TupleTag that was passed to CoGroupByKey", e);
}

When it happens

Trigger: Calling result.getAll(tag) with a TupleTag that was not registered in the CoGroupByKey transform's TaggedKeyedPCollectionTuple — e.g. a tag from a different co-group, a tag created fresh with the same id but different identity, or a typo'd tag.

Common situations: Refactoring pipelines so a tag is removed from the co-group but result consumers still reference it; constructing TupleTag literals inline (identity mismatch) instead of reusing the constants passed to CoGroupByKey; copying example code with different tags.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

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.
• union tag ${unionTag} has no corresponding tuple tag in the
• Unexpected join type

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