apache/beam · error · IllegalArgumentException

The PCollection tuple must have the DicomIO.ReadStudyMetadat

Error message

The PCollection tuple must have the DicomIO.ReadStudyMetadata.METADATA and DicomIO.ReadStudyMetadata.ERROR_MESSAGE tuple tags

What it means

DicomIO.ReadStudyMetadata.Result.of() validates that the incoming PCollectionTuple exposes exactly the expected TupleTags: DicomIO.ReadStudyMetadata.METADATA and DicomIO.ReadStudyMetadata.ERROR_MESSAGE. If the tuple lacks either tag, a Result cannot be constructed to represent the success/error split output, so an IllegalArgumentException is thrown. This is a fail-fast guard ensuring downstream writers can always call .get(METADATA) and .get(ERROR_MESSAGE).

Source

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

      /** Contains both the response and error outputs from the transformation. */
      PCollectionTuple pct;

      /**
       * Create DicomIO.ReadStudyMetadata.Result from PCollectionTuple which contains the response
       * (with METADATA and ERROR_MESSAGE tags).
       *
       * @param pct the pct
       * @return the read result
       * @throws IllegalArgumentException the illegal argument exception
       */
      static ReadStudyMetadata.Result of(PCollectionTuple pct) throws IllegalArgumentException {
        if (pct.getAll()
            .keySet()
            .containsAll((Collection<?>) TupleTagList.of(METADATA).and(ERROR_MESSAGE))) {
          return new ReadStudyMetadata.Result(pct);
        } else {
          throw new IllegalArgumentException(
              "The PCollection tuple must have the DicomIO.ReadStudyMetadata.METADATA "
                  + "and DicomIO.ReadStudyMetadata.ERROR_MESSAGE tuple tags");
        }
      }

      private Result(PCollectionTuple pct) {
        this.pct = pct;
        this.readResponse = pct.get(METADATA);
        this.failedReads = pct.get(ERROR_MESSAGE);
      }

      /**
       * Gets failed reads.
       *
       * @return the failed reads
       */
      public PCollection<String> getFailedReads() {
        return failedReads;

View on GitHub (pinned to 12126d8942)

Solutions

Create the PCollectionTuple with both tags applied: pct.apply(METADATA, ...) and pct.apply(ERROR_MESSAGE, ...) before calling Result.of(pct)
Use the exact public constants DicomIO.ReadStudyMetadata.METADATA and .ERROR_MESSAGE rather than locally created TupleTag instances
Verify with pct.has(METADATA) && pct.has(ERROR_MESSAGE) before invoking of()
Check that your pipeline stage returns a PCollectionTuple, not a single PCollection

Example fix

// before
PCollectionTuple pct = ...only metadata...;
Result result = Result.of(pct);
// after
PCollectionTuple pct = pipeline.apply(new ReadStudyMetadata()).getOutput();
pct.apply(DicomIO.ReadStudyMetadata.METADATA, metadataPc);
pct.apply(DicomIO.ReadStudyMetadata.ERROR_MESSAGE, errorPc);
Result result = Result.of(pct);

Defensive patterns

Strategy: validation

Validate before calling

if (pct.has(DicomIO.ReadStudyMetadata.METADATA) && pct.has(DicomIO.ReadStudyMetadata.ERROR_MESSAGE)) {
  Result r = DicomIO.ReadStudyMetadata.Result.of(pct);
}

Try / catch

try {
  Result r = ReadStudyMetadata.Result.of(pct);
} catch (IllegalArgumentException e) {
  LOG.error("PCollectionTuple missing METADATA/ERROR_MESSAGE tags", e);
}

Prevention

Always reference the public METADATA/ERROR_MESSAGE constants when building tuples
Let the ReadStudyMetadata transform produce the Result instead of hand-assembling PCollections
Add a pipeline-construction unit test asserting Result.of() succeeds

When it happens

Trigger: Calling ReadStudyMetadata.Result.of(pct) on a PCollectionTuple that was created without applying both METADATA and ERROR_MESSAGE TupleTags, or one built with different/renamed tags.

Common situations: Wiring a custom pipeline stage that produced only the metadata side; copy-pasting tag definitions so a locally re-declared TupleTag is not the same instance as the constant; refactoring that renamed tags while Result.of still checks the originals.

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