apache/beam · error · IllegalArgumentException

the bound has overflown double type.

Error message

the bound has overflown double type.

What it means

Histogram.BucketBounds.exponential(scale, growthFactor, numBoundedBuckets) computes bucket bounds as scale * growthFactor^i for i in [0, numBoundedBuckets]. If any computed bound exceeds Double.MAX_VALUE it becomes infinite, and the method throws this IllegalArgumentException rather than returning a histogram with infinite bounds, because such bounds cannot be represented as finite doubles.

Source

Thrown at sdks/java/extensions/combiners/src/main/java/org/apache/beam/sdk/extensions/combiners/Histogram.java:183

    public static BucketBounds exponential(
        double scale,
        double growthFactor,
        int numBoundedBuckets,
        BoundsInclusivity boundsInclusivity) {
      checkArgument(scale > 0.0, "scale should be positive.");
      checkArgument(growthFactor > 1.0, "growth factor should be greater than 1.0.");
      checkArgument(
          numBoundedBuckets > 0, "number of bounded buckets should be greater than zero.");
      checkArgument(
          numBoundedBuckets <= Integer.MAX_VALUE - 2,
          "number of bounded buckets should be less than max value of integer.");

      ImmutableList.Builder<Double> boundsCalculated = new ImmutableList.Builder<>();
      // The number of bounds is equal to the numBoundedBuckets + 1.
      for (int i = 0; i <= numBoundedBuckets; i++) {
        double bound = scale * Math.pow(growthFactor, i);
        if (Double.isInfinite(bound)) {
          throw new IllegalArgumentException("the bound has overflown double type.");
        }
        boundsCalculated.add(bound);
      }

      return new AutoValue_Histogram_BucketBounds(boundsCalculated.build(), boundsInclusivity);
    }

    /**
     * Like {@link #exponential(double, double, int, BoundsInclusivity)}, but sets
     * BoundsInclusivity.LOWER_BOUND_INCLUSIVE_UPPER_BOUND_EXCLUSIVE value for the boundsInclusivity
     * parameter.
     */
    public static BucketBounds exponential(
        double scale, double growthFactor, int numBoundedBuckets) {
      return exponential(
          scale,
          growthFactor,
          numBoundedBuckets,

View on GitHub (pinned to 12126d8942)

Solutions

1. Reduce numBoundedBuckets or growthFactor so scale * growthFactor^numBoundedBuckets stays below ~1.8e308.
2. Reduce scale if it is larger than the smallest value you actually need to bucket.
3. Compute Math.log(growthFactor) bounds check up front: if Math.log10(scale) + numBoundedBuckets*Math.log10(growthFactor) > ~308, pick smaller parameters.
4. Catch IllegalArgumentException and fall back to linear bounds or fewer buckets.

Example fix

// before
Histogram.BucketBounds bounds =
    BucketBounds.exponential(1e10, 100, 200); // 1e10 * 100^200 overflows double

// after
Histogram.BucketBounds bounds =
    BucketBounds.exponential(1e10, 10, 30); // max bound 1e10 * 10^30 = 1e40, safe

double maxBound = scale * Math.pow(growthFactor, numBoundedBuckets);
if (Double.isInfinite(maxBound)) {
  throw new IllegalArgumentException(
      "scale*growthFactor^numBoundedBuckets overflows double; reduce parameters");
}
Histogram.BucketBounds bounds = BucketBounds.exponential(scale, growthFactor, numBoundedBuckets);

try {
  bounds = BucketBounds.exponential(scale, growthFactor, numBuckets);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("overflown double")) {
    bounds = BucketBounds.exponential(scale, Math.sqrt(growthFactor), numBuckets); // fallback
  } else { throw e; }
}

When it happens

Trigger: Calling BucketBounds.exponential with scale * growthFactor^numBoundedBuckets > Double.MAX_VALUE (~1.8e308) — e.g., scale=1e10, growthFactor=100, numBoundedBuckets=200, or any large growthFactor with enough buckets.

Common situations: Configuring an exponential histogram for a very wide value range with a large growth factor and many buckets; copy-pasted parameters tuned for a different data scale; computing bounds programmatically without checking magnitude.

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

• Cannot merge schemas with different numbers of fields. schem
• Attempting to call and() on a CoGbkResult apparently not cre
• must have at least one input to a KeyedPCollections
• Unsupported type of %s: %s
• Can't convert 'null' to non-nullable field

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