apache/beam · error · IllegalArgumentException

Threshold must be a positive integer

Error message

Threshold must be a positive integer

What it means

BundleLifter's constructor requires the batch size threshold to be strictly positive. The threshold decides when a batch is treated as large; zero or negative values would make batching logic nonsensical, so the constructor rejects them.

Source

Thrown at sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/BundleLifter.java:139

  }

  private BundleLifter(TupleTag<T> smallBatchTag, TupleTag<T> largeBatchTag, int threshold) {
    this(smallBatchTag, largeBatchTag, threshold, x -> 1);
  }

  private BundleLifter(
      TupleTag<T> smallBatchTag,
      TupleTag<T> largeBatchTag,
      int threshold,
      SerializableFunction<T, Integer> elementSizer) {
    if (smallBatchTag == null || largeBatchTag == null) {
      throw new IllegalArgumentException("smallBatchTag and largeBatchTag must not be null");
    }
    if (smallBatchTag.getId().equals(largeBatchTag.getId())) {
      throw new IllegalArgumentException("smallBatchTag and largeBatchTag must be different");
    }
    if (threshold <= 0) {
      throw new IllegalArgumentException("Threshold must be a positive integer");
    }

    this.smallBatchTag = smallBatchTag;
    this.largeBatchTag = largeBatchTag;
    this.threshold = threshold;
    this.elementSizer = elementSizer;
  }

  public static <T> BundleLifter<T> of(
      TupleTag<T> smallBatchTag, TupleTag<T> largeBatchTag, int threshold) {
    return new BundleLifter<>(smallBatchTag, largeBatchTag, threshold);
  }

  public static <T> BundleLifter<T> of(
      TupleTag<T> smallBatchTag,
      TupleTag<T> largeBatchTag,
      int threshold,
      SerializableFunction<T, Integer> elementSizer) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a threshold of at least 1 when constructing BundleLifter.
2. Validate the pipeline option/config value before constructing BundleLifter and fail with a clear message.
3. Fix the default value in your options class to a sensible positive number.

Example fix

// before
int threshold = options.getBatchThreshold(); // 0
BundleLifter<T> lifter = new BundleLifter<>(td, cls, supplier, smallTag, largeTag, threshold, sizer);
// after
int threshold = Math.max(1, options.getBatchThreshold());
BundleLifter<T> lifter = new BundleLifter<>(td, cls, supplier, smallTag, largeTag, threshold, sizer);

checkArgument(threshold > 0, "Batch threshold must be positive, got %s", threshold);

When it happens

Trigger: Calling new BundleLifter<>(...) with threshold <= 0 — e.g., passing 0, a negative value, or a value read from pipeline options/default configuration that was never validated.

Common situations: A pipeline option for batch threshold defaulting to 0 ('disabled' intended); computing threshold dynamically (e.g., targetSize - overhead) yielding <= 0; user passing negative values in configuration files.

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

• smallBatchTag and largeBatchTag must be different
• Encountered an error when parsing filter: '{filter}'
• Unsupported operation '{operation}' in filter expression: {c
• Unsupported operands for expression: {call}
• Unexpected date type: {typeName}

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