apache/beam · error · IllegalArgumentException

Either elementURI or elementContents should be non-null

Error message

Either elementURI or elementContents should be non-null

What it means

getVideoAnnotationResults builds a Google Video Intelligence AnnotateVideoRequest from either a GCS URI or inline bytes. If both elementURI and elementContents are null there is no video source to send, so it throws IllegalArgumentException. Exactly one input source must be present.

Solutions

Ensure every input element has either a valid GCS URI or non-null contents before processing.
Add an upstream check that rejects/logs elements lacking both fields.
If reading inline bytes, verify the file read succeeded and contents were set on the element.
Pass a correct gs:// URI to the transform's input source.

Example fix

// before
processElement(... ) { result = getVideoAnnotationResults(element.getURI(), element.getContents(), ...); } // both may be null
// after
if (element.getURI() == null && element.getContents() == null) { throw new IllegalStateException("Element has no video source"); }
result = getVideoAnnotationResults(element.getURI(), element.getContents(), ...);

Defensive patterns

Strategy: validation

Validate before calling

if (element.getURI() == null && element.getContents() == null) throw new IllegalArgumentException("Video element lacks URI and contents");

Try / catch

try { getVideoAnnotationResults(uri, contents, ...); } catch (IllegalArgumentException e) { LOG.warn("Skipping element without video source"); return; }

Prevention

Validate input elements in a preceding DoFn
Ensure file reads populate contents before processing
Log and dead-letter elements missing sources

When it happens

Trigger: Calling getVideoAnnotationResults on an element where neither the GCS URI nor the raw video contents were populated (both null).

Common situations: Upstream DoFn/windowing producing elements with missing metadata; a malformed Pub/Sub or file record without a URI; clearing one field while assuming the other is set.

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

Appendix: source

Thrown at sdks/java/extensions/ml/src/main/java/org/apache/beam/sdk/extensions/ml/AnnotateVideoFn.java:91

   * Call the Video Intelligence Cloud AI service and return annotation results.
   *
   * @param elementURI This or elementContents is required. GCS address of video to be annotated
   * @param elementContents this or elementURI is required. Hex-encoded contents of video to be
   *     annotated
   * @param videoContext Optional context for video annotation.
   * @return
   */
  List<VideoAnnotationResults> getVideoAnnotationResults(
      String elementURI, ByteString elementContents, VideoContext videoContext)
      throws InterruptedException, ExecutionException {
    AnnotateVideoRequest.Builder requestBuilder =
        AnnotateVideoRequest.newBuilder().addAllFeatures(featureList);
    if (elementURI != null) {
      requestBuilder.setInputUri(elementURI);
    } else if (elementContents != null) {
      requestBuilder.setInputContent(elementContents);
    } else {
      throw new IllegalArgumentException("Either elementURI or elementContents should be non-null");
    }
    if (videoContext != null) {
      requestBuilder.setVideoContext(videoContext);
    }
    AnnotateVideoRequest annotateVideoRequest = requestBuilder.build();
    OperationFuture<AnnotateVideoResponse, AnnotateVideoProgress> annotateVideoAsync =
        videoIntelligenceServiceClient.annotateVideoAsync(annotateVideoRequest);
    return annotateVideoAsync.get().getAnnotationResultsList();
  }

  /** Process element implementation required. */
  @ProcessElement
  public abstract void processElement(ProcessContext context)
      throws ExecutionException, InterruptedException;
}

View on GitHub (pinned to 12126d8942)