apache/beam · error · ValueError

bucket_boundaries must be a non-empty sorted list of…

Error message

bucket_boundaries must be a non-empty sorted list of positive values.

What it means

Raised when BatchElements' bucket_boundaries is provided but invalid: empty, containing non-positive values, or not sorted ascending. Bucket boundaries define increasing edges between batch-size buckets, so they must be a non-empty, strictly positive, sorted list.

Solutions

Sort ascending and ensure all values are > 0: boundaries = sorted(b for b in boundaries if b > 0).
Guard for emptiness before constructing: if not boundaries: skip bucket_boundaries or use defaults.
Sanity-check the list: assert boundaries == sorted(boundaries) and all(b > 0 for b in boundaries).
If generating from a set/dict, convert via sorted() to fix ordering.

Example fix

// before
beam.BatchElements(bucket_boundaries=[100, 10, 0], length_fn=len)

// after
boundaries = sorted(b for b in [100, 10, 0] if b > 0)  # [10, 100]
beam.BatchElements(bucket_boundaries=boundaries, length_fn=len)

Defensive patterns

Strategy: validation

Validate before calling

if bucket_boundaries is not None:
    assert bucket_boundaries, 'bucket_boundaries must be non-empty'
    assert all(b > 0 for b in bucket_boundaries), 'bucket_boundaries must be positive'
    assert bucket_boundaries == sorted(bucket_boundaries), 'bucket_boundaries must be sorted ascending'

Type guard

def valid_bucket_boundaries(bounds):
    return (isinstance(bounds, (list, tuple)) and len(bounds) > 0
            and all(isinstance(b, (int, float)) and b > 0 for b in bounds)
            and list(bounds) == sorted(bounds))

Try / catch

try:
    t = beam.BatchElements(bucket_boundaries=bounds, length_fn=length_fn)
except ValueError as e:
    if 'bucket_boundaries must be' in str(e):
        bounds = sorted({b for b in bounds if b > 0})
        t = beam.BatchElements(bucket_boundaries=bounds, length_fn=length_fn)
    else:
        raise

Prevention

Normalize boundaries with sorted(b for b in bounds if b > 0) before passing.
Never build boundaries from sets/dicts without sorting.
Exclude 0 and negatives explicitly; boundaries are edges above the minimum, not inclusive lower bounds.

When it happens

Trigger: BatchElements(bucket_boundaries=[], length_fn=len); boundaries with 0 or negative values ([0, 10, 100]); unsorted boundaries ([100, 10]).

Common situations: Building boundaries programmatically (e.g. from a dict or set, losing order); including 0 as a lower bound; sorting descending by mistake; filtering that removed all boundaries.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/util.py:1091

      min_batch_size=1,
      max_batch_size=10000,
      target_batch_overhead=.05,
      target_batch_duration_secs=10,
      target_batch_duration_secs_including_fixed_cost=None,
      max_batch_duration_secs=None,
      *,
      element_size_fn=lambda x: 1,
      variance=0.25,
      clock=time.time,
      record_metrics=True,
      length_fn=None,
      bucket_boundaries=None):
    if bucket_boundaries is not None and length_fn is None:
      raise ValueError('bucket_boundaries requires length_fn to be set.')
    if bucket_boundaries is not None:
      if (not bucket_boundaries or any(b <= 0 for b in bucket_boundaries) or
          bucket_boundaries != sorted(bucket_boundaries)):
        raise ValueError(
            'bucket_boundaries must be a non-empty sorted list of '
            'positive values.')
    self._batch_size_estimator = _BatchSizeEstimator(
        min_batch_size=min_batch_size,
        max_batch_size=max_batch_size,
        target_batch_overhead=target_batch_overhead,
        target_batch_duration_secs=target_batch_duration_secs,
        target_batch_duration_secs_including_fixed_cost=(
            target_batch_duration_secs_including_fixed_cost),
        variance=variance,
        clock=clock,
        record_metrics=record_metrics)
    self._element_size_fn = element_size_fn
    self._max_batch_dur = max_batch_duration_secs
    self._clock = clock
    self._length_fn = length_fn
    if length_fn is not None and bucket_boundaries is None:
      self._bucket_boundaries = self._DEFAULT_BUCKET_BOUNDARIES

View on GitHub (pinned to 12126d8942)