apache/beam · error · IllegalArgumentException

sample size must be >= 0

Error message

sample size must be >= 0

What it means

Sample.fixedSizeGlobally/sampleFn constructs FixedSizedSampleFn, which validates that the requested sample size is non-negative; a negative size is meaningless and throws IllegalArgumentException in the constructor. Zero is allowed (yields empty samples).

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Sample.java:306

    }
  }

  /**
   * {@code CombineFn} that computes a fixed-size sample of a collection of values.
   *
   * @param <T> the type of the elements
   */
  public static class FixedSizedSampleFn<T>
      extends CombineFn<
          T, Top.BoundedHeap<KV<Integer, T>, SerializableComparator<KV<Integer, T>>>, Iterable<T>> {
    private final int sampleSize;
    private final Top.TopCombineFn<KV<Integer, T>, SerializableComparator<KV<Integer, T>>>
        topCombineFn;
    private final Random rand = new Random();

    private FixedSizedSampleFn(int sampleSize) {
      if (sampleSize < 0) {
        throw new IllegalArgumentException("sample size must be >= 0");
      }

      this.sampleSize = sampleSize;
      topCombineFn = new Top.TopCombineFn<>(sampleSize, new KV.OrderByKey<>());
    }

    @Override
    public Top.BoundedHeap<KV<Integer, T>, SerializableComparator<KV<Integer, T>>>
        createAccumulator() {
      return topCombineFn.createAccumulator();
    }

    @Override
    public Top.BoundedHeap<KV<Integer, T>, SerializableComparator<KV<Integer, T>>> addInput(
        Top.BoundedHeap<KV<Integer, T>, SerializableComparator<KV<Integer, T>>> accumulator,
        T input) {
      accumulator.addInput(KV.of(rand.nextInt(), input));
      return accumulator;

View on GitHub (pinned to 12126d8942)

Solutions

1. Validate sample size >= 0 before calling Sample.fixedSizeGlobally/PerKey
2. Clamp with Math.max(0, size)
3. Check the source of the size (config/user input) for negative defaults

Example fix

// before
int n = getSampleSizeFromConfig(); // may be -1
PCollection<T> sampled = input.apply(Sample.fixedSizeGlobally(n));
// after
int n = Math.max(0, getSampleSizeFromConfig());
PCollection<T> sampled = input.apply(Sample.fixedSizeGlobally(n));

if (sampleSize < 0) { throw new IllegalArgumentException("sample size must be >= 0"); }

When it happens

Trigger: Calling Sample.fixedSizeGlobally(n) or Sample.fixedSizePerKey(n) with n < 0, typically from a config value, subtraction, or user input not validated.

Common situations: Config values unset and later negated; computing sample size as a percentage of something that is negative; user-supplied CLI argument not validated.

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

• numPartitions must be > 0
• offset is negative:
• offset exceeds the buffer limit. offset: , limit:
• length is negative:
• offset + length exceeds the buffer limit. offset: , length:

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