apache/beam · error · IllegalArgumentException

The input PCollectionTuple has tags: ${inputTags} and the jo

Error message

The input PCollectionTuple has tags: ${inputTags} and the join was specified for tags ${joinTags}. These do not match.

What it means

CoGroup.Impl.verify checks that the set of tags in the input PCollectionTuple exactly equals the set of tags for which join arguments were specified. A mismatch (extra inputs, missing clauses, or misspelled tags) throws IllegalArgumentException listing both sets.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/transforms/CoGroup.java:458

                        new RowSelectorContainer(schema, keyFields, true);

                    @ProcessElement
                    public void process(@Element Row row, OutputReceiver<KV<Row, Row>> o) {
                      o.output(KV.of(rowSelector.select(row), row));
                    }
                  }))
          .setCoder(KvCoder.of(SchemaCoder.of(keySchema), SchemaCoder.of(schema)));
    }
  }

  static void verify(PCollectionTuple input, JoinArguments joinArgs) {
    if (joinArgs.allInputsJoinArgs == null) {
      // If explicit join tags were specified, then they must match the input tuple.
      Set<String> inputTags =
          input.getAll().keySet().stream().map(TupleTag::getId).collect(Collectors.toSet());
      Set<String> joinTags = joinArgs.joinArgsMap.keySet();
      if (!inputTags.equals(joinTags)) {
        throw new IllegalArgumentException(
            "The input PCollectionTuple has tags: "
                + inputTags
                + " and the join was specified for tags "
                + joinTags
                + ". These do not match.");
      }
    }
  }

  @AutoValue
  public abstract static class Result {
    abstract Row getKey();

    abstract List<Iterable<Row>> getIterables();

    abstract List<String> getTags();

    abstract JoinArguments getJoinArguments();

View on GitHub (pinned to 12126d8942)

Solutions

1. Make the join tag set exactly match the tuple's tags: add or remove join(tag, By...) clauses accordingly.
2. Compare TupleTag.getId() strings, not TupleTag object references, when specifying tags.
3. Use the allInputs byFields(...) global form so tag matching is not required.
4. Log both sets (they are in the message) and fix the divergent side.

Example fix

// before
CoGroup.join("left", By.field("k")).join("right", By.field("k"))
    .from(tupleWithThreeInputs); // tags {left,right,extra}
// after
CoGroup.join("left", By.field("k")).join("right", By.field("k"))
    .join("extra", By.field("k"))
    .from(tupleWithThreeInputs);

Set<String> inputTags = tuple.getAll().keySet().stream().map(TupleTag::getId).collect(Collectors.toSet());
Set<String> joinTags = joinArgsMap.keySet();
if (!inputTags.equals(joinTags)) { log.warn("tag mismatch: {} vs {}", inputTags, joinTags); }

try { result = coGroup.expand(tuple); } catch (IllegalArgumentException e) { if (e.getMessage().contains("These do not match")) { /* reconcile tag sets */ } else throw e; }

When it happens

Trigger: Expanding a CoGroup.Impl where joinArgs.joinArgsMap.keySet() differs from input.getAll() tag ids — e.g. joining on tags {a,b} while the tuple contains {a,b,c}, or per-tag join() calls using tag strings that don't match TupleTag.getId().

Common situations: TupleTag instances created with new TupleTag<>("in1") whose getId() differs from the plain object identity keys users assume; adding inputs to the tuple after specifying join clauses; typos in tag strings.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• No fields were set for input ${tag}
• Cannot set both a global and per-tag fields.
• union tag ${unionTag} has no corresponding tuple tag in the
• TupleTag ${tag} is not in the schema
• Unexpected join type

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