apache/beam · error · IllegalArgumentException

Scale should be greater than

Error message

Scale should be greater than %d: %d

What it means

ExponentialBuckets.of(scale, numBuckets) validates the base-2 exponent scale against MINIMUM_SCALE before building the histogram bucket scheme. A scale below the minimum cannot represent a valid exponential histogram, so an IllegalArgumentException is thrown naming the required minimum.

Solutions

1. Pass a scale value >= MINIMUM_SCALE (check the constant in HistogramData for the exact bound)
2. Clamp computed scale values: Math.max(MINIMUM_SCALE, computedScale) before calling of()
3. Review where the scale originates; unit-test boundary values

Example fix

// before
ExponentialBuckets b = ExponentialBuckets.of(-2, 16);
// after
int scale = Math.max(HistogramData.ExponentialBuckets.MINIMUM_SCALE, computedScale);
ExponentialBuckets b = ExponentialBuckets.of(scale, 16);

if (scale < HistogramData.ExponentialBuckets.MINIMUM_SCALE) {
  throw new IllegalArgumentException("scale below minimum: " + scale);
}

try {
  buckets = ExponentialBuckets.of(scale, numBuckets);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Invalid histogram scale config: " + scale, e);
}

When it happens

Trigger: Calling HistogramData.ExponentialBuckets.of(scale, numBuckets) with a negative or too-small scale value (scale < MINIMUM_SCALE).

Common situations: Computing scale dynamically (e.g. from a width or resolution calculation) and the formula yields 0 or negative values; hardcoding scale values copied from other histogram APIs with different conventions.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• numBuckets should be greater than zero
• 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/9d8887a7a9bd3b90. Report an issue: GitHub.

Appendix: source

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

     */
    @Memoized
    public double getInvLog2GrowthFactor() {
      return Math.pow(2, getScale());
    }

    @Override
    public abstract int getNumBuckets();

    /* Memoized since this value is used everytime a datapoint is recorded. */
    @Memoized
    @Override
    public double getRangeTo() {
      return Math.pow(getBase(), getNumBuckets());
    }

    public static ExponentialBuckets of(int scale, int numBuckets) {
      if (scale < MINIMUM_SCALE) {
        throw new IllegalArgumentException(
            String.format("Scale should be greater than %d: %d", MINIMUM_SCALE, scale));
      }

      if (scale > MAXIMUM_SCALE) {
        throw new IllegalArgumentException(
            String.format("Scale should be less than %d: %d", MAXIMUM_SCALE, scale));
      }
      if (numBuckets <= 0) {
        throw new IllegalArgumentException(
            String.format("numBuckets should be positive: %d", numBuckets));
      }

      int clippedNumBuckets = ExponentialBuckets.computeNumberOfBuckets(scale, numBuckets);
      return new AutoValue_HistogramData_ExponentialBuckets(scale, clippedNumBuckets);
    }

    /**
     * numBuckets is clipped so that the largest bucket's lower bound is not greater than 2^32-1

View on GitHub (pinned to 12126d8942)