apache/beam · error · ValueError

Expected non-negative n, received

Error message

Expected non-negative n, received %s.

What it means

ValueError raised by `Sample.FixedSizeGlobally/FixedSizePerKey.__init__` when the sample size `n` is negative. Sampling cannot request fewer than zero elements, so Beam validates the argument at transform construction time.

Solutions

1. Pass a non-negative integer for n.
2. Clamp computed sizes: `n = max(0, computed_n)`.
3. Validate configuration values before constructing the combiner.

Example fix

// before
sampled = pcoll | beam.combiners.Sample.FixedSizeGlobally(size - dropped)
// after
n = max(0, size - dropped)
sampled = pcoll | beam.combiners.Sample.FixedSizeGlobally(n)

if n < 0:
    raise ValueError(f'sample size must be non-negative, got {n}')
pcoll | beam.combiners.Sample.FixedSizeGlobally(n)

def is_valid_sample_size(n) -> bool:
    return isinstance(n, int) and n >= 0

When it happens

Trigger: `beam.combiners.Sample.FixedSizeGlobally(-1)` or `Sample.FixedSizePerKey(n=-1)` (e.g. n computed from a variable/config that went negative).

Common situations: Passing a computed size without clamping (e.g. `len(x) - k` underflow), or misreading the parameter as a percentage.

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 specify both 'labels' and 'index'/'columns'
• Field expression %r at
• Invalid Firestore document name
• length is negative:
• List of SerializableFunction must be the same size as the…

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/combiners.py:612

    def display_data(self):
      return {'n': self._n}

    def default_label(self):
      return 'FixedSizePerKey(%d)' % self._n

  @with_input_types(T)
  @with_output_types(T)
  class Any(ptransform.PTransform):
    """Returns up to n arbitrary elements from the input PCollection.

    This is the Python equivalent of Java's ``Sample.any``. Unlike
    ``FixedSizeGlobally`` it does not sample uniformly at random, and it returns
    the selected elements rather than a single list. If the input has fewer than
    n elements, all of them are returned.
    """
    def __init__(self, n):
      if n < 0:
        raise ValueError('Expected non-negative n, received %s.' % n)
      self._n = n

    def expand(self, pcoll):
      return (
          pcoll
          | core.CombineGlobally(_SampleAnyCombineFn(
              self._n)).without_defaults()
          | core.FlatMap(lambda elements: elements).with_input_types(
              list[T]).with_output_types(T))

    def display_data(self):
      return {'n': self._n}

    def default_label(self):
      return 'Any(%d)' % self._n


@with_input_types(T)

View on GitHub (pinned to 12126d8942)