apache/beam · error · IllegalArgumentException

Tag not found in this PCollectionRowTuple tuple

Error message

Tag not found in this PCollectionRowTuple tuple

What it means

PCollectionRowTuple.get(tag) found no entry for the requested tag in its tag-to-PCollection map — pcollectionMap.get returned null. The tag string is the faulty input: it was never added via of(...)/and(...), i.e. has(tag) is false, matching the documented contract that get throws for unknown tags.

Solutions

Check tuple.has(tag) before calling get(tag)
Verify the tag string matches the one used in and() or the transform's output tags exactly
List known tags (e.g. log the map keys) to confirm the correct tag name

Example fix

// before
PCollection<Row> pc = tuple.get("Counts"); // throws if tag is "counts"
// after
PCollection<Row> pc = tuple.has("counts")
    ? tuple.get("counts")
    : fallbackPCollection;

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean hasTag(PCollectionRowTuple t, String tag) { return t.has(tag); }

Try / catch

try { return tuple.get(tag); } catch (IllegalArgumentException e) { return null; /* or default */ }

Prevention

Define tag names as constants shared by writer and reader
Call has(tag) before get(tag)
Log available tag keys when a lookup fails

When it happens

Trigger: Calling get(tag) with a tag never added via and()/of(), or with a tag whose spelling/case differs from the key used when adding.

Common situations: Typos in output tag strings; renaming a tag in the writer but not the reader; reading a tuple output produced by a transform with different tag names.

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/cd99faa8800e1e5f. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionRowTuple.java:179

  /**
   * Returns whether this {@link PCollectionRowTuple} contains a {@link PCollection} with the given
   * tag.
   */
  public boolean has(String tag) {
    return pcollectionMap.containsKey(tag);
  }

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

  /**
   * Like {@link #get(String)}, but is a convenience method to get a single PCollection without
   * providing a tag for that output. Use only when there is a single collection in this tuple.
   *
   * <p>Throws {@link IllegalStateException} if more than one output exists in the {@link
   * PCollectionRowTuple}.
   */
  public PCollection<Row> getSinglePCollection() {
    Preconditions.checkState(
        pcollectionMap.size() == 1,
        "Expected exactly one output PCollection<Row>, but found %s. "
            + "Please try retrieving a specified output using get(<tag>) instead.",
        pcollectionMap.size());
    return get(pcollectionMap.entrySet().iterator().next().getKey());

View on GitHub (pinned to 12126d8942)