apache/beam · error · IllegalArgumentException

numBuckets should be greater than zero

Error message

numBuckets should be greater than zero: %d

What it means

LinearBuckets.of(start, width, numBuckets) requires at least one bucket. Passing numBuckets <= 0 yields a histogram with no buckets, which cannot be encoded or populated, so this IllegalArgumentException is thrown.

Solutions

1. Ensure numBuckets >= 1 before calling of()
2. Treat 0/negative config values as unset and apply a default bucket count
3. Validate at configuration load time rather than at histogram construction

Example fix

// before
int numBuckets = config.get("buckets", 0);
LinearBuckets.of(start, width, numBuckets);
// after
int numBuckets = Math.max(1, config.get("buckets", DEFAULT_NUM_BUCKETS));
LinearBuckets.of(start, width, numBuckets);

if (numBuckets <= 0) {
  throw new IllegalArgumentException("numBuckets must be positive, got: " + numBuckets);
}

try {
  buckets = LinearBuckets.of(start, width, numBuckets);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Invalid bucket count: " + numBuckets, e);
}

When it happens

Trigger: Calling LinearBuckets.of(start, width, numBuckets) with numBuckets zero or negative — typically from an uninitialized/zero-default config value or a division-derived bucket count that rounds to 0.

Common situations: Config where numBuckets defaults to 0 meaning 'not set'; integer division truncation producing 0; user input not validated before building bucket definitions.

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

• Scale should be greater than
• Scale should be less than
• width should be greater than zero
• ApproximateUnique needs a sampleSize >= 16 for an…
• ApproximateUnique needs an estimation error between 1%…

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/HistogramData.java:658

    public abstract int hashCode();
  }

  @AutoValue
  public abstract static class LinearBuckets implements BucketType {
    public abstract double getStart();

    public abstract double getWidth();

    @Override
    public abstract int getNumBuckets();

    public static LinearBuckets of(double start, double width, int numBuckets) {
      if (width <= 0) {
        throw new IllegalArgumentException(
            String.format("width should be greater than zero: %f", width));
      }
      if (numBuckets <= 0) {
        throw new IllegalArgumentException(
            String.format("numBuckets should be greater than zero: %d", numBuckets));
      }
      return new AutoValue_HistogramData_LinearBuckets(start, width, numBuckets);
    }

    @Override
    public int getBucketIndex(double value) {
      return DoubleMath.roundToInt((value - getStart()) / getWidth(), RoundingMode.FLOOR);
    }

    @Override
    public double getBucketSize(int index) {
      return getWidth();
    }

    @Override
    public double getAccumulatedBucketSize(int endIndex) {
      return getWidth() * endIndex;

View on GitHub (pinned to 12126d8942)