apache/beam · error · IllegalArgumentException

Scale should be less than

Error message

Scale should be less than %d: %d

What it means

ExponentialBuckets.of(scale, numBuckets) also enforces an upper bound: scale greater than MAXIMUM_SCALE throws this IllegalArgumentException because such an exponent would overflow bucket-range representation. The message names the maximum allowed scale.

Solutions

  1. Clamp scale to <= MAXIMUM_SCALE before calling of()
  2. Validate user-supplied histogram configuration at pipeline-construction time
  3. Check that the scale isn't accidentally expressed in different units (e.g. bits vs digits)

Example fix

// before
int scale = userConfig.getScale(); // could be 1000
ExponentialBuckets.of(scale, 32);
// after
int scale = Math.min(HistogramData.ExponentialBuckets.MAXIMUM_SCALE, userConfig.getScale());
ExponentialBuckets.of(scale, 32);
Defensive patterns

Strategy: validation

Validate before calling

if (scale > HistogramData.ExponentialBuckets.MAXIMUM_SCALE) {
  throw new IllegalArgumentException("scale exceeds maximum: " + scale);
}

Try / catch

try {
  buckets = ExponentialBuckets.of(scale, numBuckets);
} catch (IllegalArgumentException e) {
  LOG.warn("Clamping scale {} to max and retrying", scale);
  buckets = ExponentialBuckets.of(HistogramData.ExponentialBuckets.MAXIMUM_SCALE, numBuckets);
}

Prevention

When it happens

Trigger: Calling ExponentialBuckets.of(scale, numBuckets) with an excessively large scale (scale > MAXIMUM_SCALE), often from unbounded user input or a derived computation without clamping.

Common situations: Accepting histogram resolution from user configuration without validating it; deriving scale from data magnitudes that produce huge exponents; copying scale constants from APIs with wider allowed ranges.

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

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

Appendix: source

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

    /* 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
     * (uint32 max). This value is log_base(2^32) which simplifies as follows:
     *
     * <pre>
     * log_base(2^32)
     * = log_2(2^32)/log_2(base)
     * = 32/(2**-scale)
     * = 32*(2**scale)
     * </pre>
     */

View on GitHub (pinned to 12126d8942)