apache/beam · error · IllegalArgumentException

TupleTag not found in this PCollectionTuple tuple

Error message

TupleTag %s not found in this PCollectionTuple tuple

What it means

PCollectionTuple.get(TupleTag) throws IllegalArgumentException when the given TupleTag is not a key in the tuple's map. Beam fails fast instead of returning null, formatting the missing tag into the message.

Solutions

  1. Check tuple.has(tag) before calling get(tag)
  2. Reuse the same TupleTag constant used when the output was added, rather than creating a new instance
  3. Confirm the transform's output tag names (via getTupleTags or docs) match the queried tag

Example fix

// before
TupleTag<String> out = new TupleTag<>("fails");
PCollection<String> pc = tuple.get(out); // throws if registered tag differs
// after
TupleTag<String> out = MY_TRANSFORM.FAILURES_TAG; // shared constant
if (tuple.has(out)) {
  PCollection<String> pc = tuple.get(out);
}
Defensive patterns

Strategy: validation

Validate before calling

if (!tuple.has(tag)) { throw new IllegalArgumentException("missing TupleTag: " + tag); }

Type guard

boolean hasTag(PCollectionTuple t, TupleTag<?> tag) { return t.has(tag); }

Try / catch

try { return tuple.get(tag); } catch (IllegalArgumentException e) { return tuple.get(knownTagConstant); }

Prevention

When it happens

Trigger: Calling get(tag) with a TupleTag that was never added via and() or produced by the source transform; using a new TupleTag<>("name") instance that differs from the one registered if tags lack proper identity semantics.

Common situations: Mismatch between output TupleTags declared in a DoFn/transform and the tags queried in the test or downstream code; constructing an equal-looking TupleTag instead of reusing the constant.

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

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionTuple.java:221

  /**
   * Returns whether this {@link PCollectionTuple} contains a {@link PCollection} with the given
   * tag.
   */
  public <T> boolean has(String tag) {
    return has(new TupleTag<>(tag));
  }

  /**
   * Returns the {@link PCollection} associated with the given {@link TupleTag} in this {@link
   * PCollectionTuple}. Throws {@link IllegalArgumentException} if there is no such {@link
   * PCollection}, i.e., {@code !has(tag)}.
   */
  public <T> PCollection<T> get(TupleTag<T> tag) {
    @SuppressWarnings("unchecked")
    PCollection<T> pcollection = (PCollection<T>) pcollectionMap.get(tag);
    if (pcollection == null) {
      throw new IllegalArgumentException(
          String.format("TupleTag %s not found in this PCollectionTuple tuple", tag));
    }
    return pcollection;
  }

  /**
   * Returns the {@link PCollection} associated with the given tag in this {@link PCollectionTuple}.
   * Throws {@link IllegalArgumentException} if there is no such {@link PCollection}, i.e., {@code
   * !has(tag)}.
   */
  public <T> PCollection<T> get(String tag) {
    return get(new TupleTag<>(tag));
  }

  /**
   * Returns an immutable Map from {@link TupleTag} to corresponding {@link PCollection}, for all
   * the members of this {@link PCollectionTuple}.
   */

View on GitHub (pinned to 12126d8942)