apache/beam · error · IllegalArgumentException

The PCollection tuple must have the HL7v2IO.Read.OUT and HL7

Error message

The PCollection tuple must have the HL7v2IO.Read.OUT and HL7v2IO.Read.DEAD_LETTER tuple tags

What it means

HL7v2IO.Read.Result.of() checks that the key set of the given PCollectionTuple contains all TupleTags of HL7v2IO.Read.OUT and HL7v2IO.Read.DEAD_LETTER. The Result wrapper is only meaningful for tuples that carry both the main output and the dead-letter output of the HL7v2IO.Read transform, so an incomplete tuple is rejected with IllegalArgumentException at authoring time.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/healthcare/HL7v2IO.java:280

   * href=https://cloud.google.com/healthcare/docs/reference/rest/v1/projects.locations.datasets.hl7V2Stores.messages/list></a>.
   */
  public static class Read extends PTransform<PCollection<String>, Read.Result> {

    public Read() {}

    /**
     * The type Result includes {@link PCollection} of {@link HL7v2Message} objects for successfully
     * read results and {@link PCollection} of {@link HealthcareIOError} objects for failed reads.
     */
    public static class Result extends HL7v2ReadResult<String, HL7v2Message> {

      public static Result of(PCollectionTuple pct) throws IllegalArgumentException {
        if (pct.getAll()
            .keySet()
            .containsAll(TupleTagList.of(Read.OUT).and(DEAD_LETTER).getAll())) {
          return new Result(pct);
        } else {
          throw new IllegalArgumentException(
              "The PCollection tuple must have the HL7v2IO.Read.OUT "
                  + "and HL7v2IO.Read.DEAD_LETTER tuple tags");
        }
      }

      private Result(PCollectionTuple pct) {
        super(pct);
        this.out = Read.OUT;
        this.messages = pct.get(OUT).setCoder(HL7v2MessageCoder.of());
        this.failedReads =
            pct.get(DEAD_LETTER).setCoder(HealthcareIOErrorCoder.of(StringUtf8Coder.of()));
      }
    }

    /** The tag for the main output of HL7v2 Messages. */
    public static final TupleTag<HL7v2Message> OUT = new TupleTag<HL7v2Message>() {};

    /** The tag for the deadletter output of HL7v2 Messages. */

View on GitHub (pinned to 12126d8942)

Solutions

Populate the tuple with pcollections keyed by HL7v2IO.Read.OUT and HL7v2IO.Read.DEAD_LETTER before calling Result.of.
Use the exact static TupleTag constants from HL7v2IO.Read rather than new TupleTag<> instances with the same id string.
Prefer building the tuple from the transform's expand() output, which is guaranteed to carry both tags.

Example fix

// before
PCollectionTuple pct = PCollectionTuple.of(new TupleTag<HL7v2Message>("out"), msgs);
HL7v2IO.Read.Result.of(pct); // throws

// after
PCollectionTuple pct = PCollectionTuple.of(HL7v2IO.Read.OUT, msgs,
    HL7v2IO.Read.DEAD_LETTER, failedMsgs);
HL7v2IO.Read.Result.of(pct);

Defensive patterns

Strategy: validation

Validate before calling

if (!pct.getAll().keySet().containsAll(TupleTagList.of(HL7v2IO.Read.OUT).and(HL7v2IO.Read.DEAD_LETTER).getAll())) {
  throw new IllegalArgumentException("HL7v2IO.Read tuple missing OUT or DEAD_LETTER");
}

Type guard

boolean isHl7v2ReadResult(PCollectionTuple pct) {
  return pct.getAll().keySet().containsAll(
      TupleTagList.of(HL7v2IO.Read.OUT).and(HL7v2IO.Read.DEAD_LETTER).getAll());
}

Try / catch

try {
  HL7v2IO.Read.Result r = HL7v2IO.Read.Result.of(pct);
} catch (IllegalArgumentException e) {
  LOG.error("Tuple tags do not match HL7v2IO.Read contract", e);
}

Prevention

Use HL7v2IO.Read.OUT and HL7v2IO.Read.DEAD_LETTER constants when calling pct.get().
Don't confuse HL7v2IO.Read tags with HL7v2IO.HL7v2Read tags.
Wire the dead-letter output even if you only discard it.

When it happens

Trigger: Calling HL7v2IO.Read.of(pct) / Result.of(pct) with a tuple missing the OUT tag, missing the DEAD_LETTER tag, or using tags declared elsewhere (custom TupleTag instances) instead of the static constants on HL7v2IO.Read.

Common situations: Hand-assembling a PCollectionTuple instead of taking the output of hl7v2IO.read(); renaming or redefining the TupleTags locally; wiring only the successful messages and skipping the dead-letter output.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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