apache/beam · error · IllegalArgumentException

bounds should be in ascending order without duplicates.

Error message

bounds should be in ascending order without duplicates.

What it means

Histogram BucketBounds.explicit() validates a user-provided list of bucket boundaries. Bounds must be strictly ascending because duplicate or non-monotonic bounds would make bucket ranges ambiguous or empty. If any bound is greater than or equal to the next one, IllegalArgumentException is thrown.

Solutions

  1. Sort the bounds list and remove duplicates before calling explicit().
  2. Ensure numeric types/formatting do not collapse distinct bounds to the same double.
  3. Validate bounds with a pre-check loop before constructing BucketBounds.

Example fix

// before
BucketBounds.explicit(Arrays.asList(5.0, 1.0, 1.0), BoundsInclusivity.LOWER_BOUND_INCLUSIVE);
// after
List<Double> bounds = new TreeSet<>(Arrays.asList(5.0, 1.0, 1.0));
BucketBounds.explicit(new ArrayList<>(bounds), BoundsInclusivity.LOWER_BOUND_INCLUSIVE);
Defensive patterns

Strategy: validation

Validate before calling

List<Double> sorted = bounds.stream().distinct().sorted().collect(Collectors.toList());
for (int i = 1; i < sorted.size(); i++) {
  if (!(sorted.get(i - 1) < sorted.get(i))) {
    throw new IllegalArgumentException("bounds must be strictly ascending");
  }
}
BucketBounds.explicit(sorted, BoundsInclusivity.LOWER_BOUND_INCLUSIVE);

Try / catch

try {
  bucketBounds = BucketBounds.explicit(configuredBounds, inclusivity);
} catch (IllegalArgumentException e) {
  bucketBounds = BucketBounds.explicit(new ArrayList<>(new TreeSet<>(configuredBounds)), inclusivity);
}

Prevention

When it happens

Trigger: Calling BucketBounds.explicit(List<Double> bounds, ...) with a list containing equal adjacent values (e.g. [1.0, 1.0, 2.0]) or descending values (e.g. [5.0, 1.0]).

Common situations: Building bounds programmatically with rounding that collapses distinct values to the same double; unsorted input from config files or user-supplied CSV data; duplicates introduced when merging boundary lists.

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/73eba9e11fd70495. Report an issue: GitHub.

Appendix: source

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

          width,
          numBoundedBuckets,
          BoundsInclusivity.LOWER_BOUND_INCLUSIVE_UPPER_BOUND_EXCLUSIVE);
    }

    /**
     * Static factory method for defining bounds of explicit histogram.
     *
     * @param bounds array of explicit bounds of the buckets.
     * @param boundsInclusivity enum value which defines if lower or upper bounds are
     *     inclusive/exclusive.
     */
    public static BucketBounds explicit(List<Double> bounds, BoundsInclusivity boundsInclusivity) {
      checkNotNull(bounds, "the bounds array should not be null.");
      checkArgument(bounds.size() > 0, "the bounds array should not be empty.");

      for (int i = 1; i < bounds.size(); i++) {
        if (bounds.get(i - 1) >= bounds.get(i)) {
          throw new IllegalArgumentException(
              "bounds should be in ascending order without duplicates.");
        }
      }

      return new AutoValue_Histogram_BucketBounds(ImmutableList.copyOf(bounds), boundsInclusivity);
    }

    /**
     * Like {@link #explicit(List, BoundsInclusivity)}, but sets
     * BoundsInclusivity.LOWER_BOUND_INCLUSIVE_UPPER_BOUND_EXCLUSIVE value for the boundsInclusivity
     * parameter.
     */
    public static BucketBounds explicit(List<Double> bounds) {
      return explicit(bounds, BoundsInclusivity.LOWER_BOUND_INCLUSIVE_UPPER_BOUND_EXCLUSIVE);
    }
  }

  /**

View on GitHub (pinned to 12126d8942)