apache/beam · error · IllegalArgumentException

width should be greater than zero

Error message

width should be greater than zero: %f

What it means

LinearBuckets.of(start, width, numBuckets) requires a strictly positive bucket width. A zero or negative width makes the linear histogram bucketing undefined (every value would map to an invalid bucket), so an IllegalArgumentException with this message is thrown.

Solutions

  1. Ensure width > 0 before calling of(); guard or throw a clearer application-level error
  2. If width is derived from data range, fall back to a sensible default when max == min
  3. Validate histogram configuration at construction time of your job options

Example fix

// before
double width = (max - min) / numBuckets; // 0 when max == min
LinearBuckets.of(min, width, numBuckets);
// after
double width = Math.max((max - min) / numBuckets, 1.0);
LinearBuckets.of(min, width, numBuckets);
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

When it happens

Trigger: Calling HistogramData.LinearBuckets.of(start, width, numBuckets) with width <= 0, e.g. width computed as (max - min)/numBuckets where max == min, or a negative user-supplied width.

Common situations: Deriving width from constant data (range of 0); config files where width defaults to 0; sign errors when computing width from differences.

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

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

Appendix: source

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

    }

    @Memoized
    @Override
    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();
    }

View on GitHub (pinned to 12126d8942)