apache/beam · error · IllegalArgumentException

The PCollection tuple must have the HL7v2IO.HL7v2Read.OUT an

Error message

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

What it means

HL7v2IO.HL7v2Read.Result.of() validates that the supplied PCollectionTuple contains PCollections under the HL7v2IO.HL7v2Read.OUT and HL7v2IO.HL7v2Read.DEAD_LETTER tuple tags. This is a distinct variant from HL7v2IO.Read (error 1961): HL7v2Read is the legacy/alternate read representation, and its Result refuses tuples that don't carry both of its own tags.

Source

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

  public static class HL7v2Read
      extends PTransform<PCollection<HL7v2ReadParameter>, HL7v2Read.Result> {

    public HL7v2Read() {}

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

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

      private Result(PCollectionTuple pct) {
        super(pct);
        this.out = HL7v2Read.OUT;
        this.messages = pct.get(OUT).setCoder(HL7v2ReadResponseCoder.of());
        this.failedReads =
            pct.get(DEAD_LETTER)
                .setCoder(
                    HealthcareIOErrorCoder.of(SerializableCoder.of(HL7v2ReadParameter.class)));
      }
    }

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

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure both PCollections are registered with HL7v2IO.HL7v2Read.OUT and HL7v2IO.HL7v2Read.DEAD_LETTER TupleTags.
2. Verify you are not passing a tuple whose tags belong to HL7v2IO.Read; each Result class requires its own transform's tags.
3. Derive the PCollectionTuple from the HL7v2Read transform's output rather than assembling it by hand.

Example fix

// before
PCollectionTuple pct = PCollectionTuple.of(HL7v2IO.Read.OUT, msgs, HL7v2IO.Read.DEAD_LETTER, fails);
HL7v2IO.HL7v2Read.Result.of(pct); // throws: wrong tags

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

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

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

try {
  HL7v2IO.HL7v2Read.Result r = HL7v2IO.HL7v2Read.Result.of(pct);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("Wrong PCollectionTuple tags for HL7v2Read.Result", e);
}

When it happens

Trigger: Calling HL7v2IO.HL7v2Read.Result.of(pct) with a tuple built for a different transform (e.g. one using HL7v2IO.Read's tags), or a tuple missing either the OUT or DEAD_LETTER PCollection.

Common situations: Mixing tags between HL7v2IO.Read and HL7v2IO.HL7v2Read after refactoring between the two APIs; only registering the successful-read PCollection; constructing the PCollectionTuple manually with ad-hoc TupleTags.

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

• The PCollection tuple must have the HL7v2IO.Read.OUT and HL7
• The PCollection tuple must have the FhirIOPatientEverything.
• The batch import API is not supported yet
• Could not find earliest send time. The filter %s matched no
• Could not find latest send time. The filter %s matched no r

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