{"record":{"id":"93bad57b7b8031e4","repo":"apache/beam","slug":"expected-non-negative-n-received-s","errorCode":null,"errorMessage":"Expected non-negative n, received %s.","messagePattern":"Expected non-negative n, received (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/combiners.py","lineNumber":612,"sourceCode":"    def display_data(self):\n      return {'n': self._n}\n\n    def default_label(self):\n      return 'FixedSizePerKey(%d)' % self._n\n\n  @with_input_types(T)\n  @with_output_types(T)\n  class Any(ptransform.PTransform):\n    \"\"\"Returns up to n arbitrary elements from the input PCollection.\n\n    This is the Python equivalent of Java's ``Sample.any``. Unlike\n    ``FixedSizeGlobally`` it does not sample uniformly at random, and it returns\n    the selected elements rather than a single list. If the input has fewer than\n    n elements, all of them are returned.\n    \"\"\"\n    def __init__(self, n):\n      if n < 0:\n        raise ValueError('Expected non-negative n, received %s.' % n)\n      self._n = n\n\n    def expand(self, pcoll):\n      return (\n          pcoll\n          | core.CombineGlobally(_SampleAnyCombineFn(\n              self._n)).without_defaults()\n          | core.FlatMap(lambda elements: elements).with_input_types(\n              list[T]).with_output_types(T))\n\n    def display_data(self):\n      return {'n': self._n}\n\n    def default_label(self):\n      return 'Any(%d)' % self._n\n\n\n@with_input_types(T)","sourceCodeStart":594,"sourceCodeEnd":630,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/combiners.py#L594-L630","documentation":"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.","triggerScenarios":"`beam.combiners.Sample.FixedSizeGlobally(-1)` or `Sample.FixedSizePerKey(n=-1)` (e.g. n computed from a variable/config that went negative).","commonSituations":"Passing a computed size without clamping (e.g. `len(x) - k` underflow), or misreading the parameter as a percentage.","solutions":["Pass a non-negative integer for n.","Clamp computed sizes: `n = max(0, computed_n)`.","Validate configuration values before constructing the combiner."],"exampleFix":"// before\nsampled = pcoll | beam.combiners.Sample.FixedSizeGlobally(size - dropped)\n// after\nn = max(0, size - dropped)\nsampled = pcoll | beam.combiners.Sample.FixedSizeGlobally(n)","handlingStrategy":"validation","validationCode":"if n < 0:\n    raise ValueError(f'sample size must be non-negative, got {n}')\npcoll | beam.combiners.Sample.FixedSizeGlobally(n)","typeGuard":"def is_valid_sample_size(n) -> bool:\n    return isinstance(n, int) and n >= 0","tryCatchPattern":null,"preventionTips":["Clamp computed sizes with max(0, value)","Validate config values feeding sample sizes","Prefer named constants over arithmetic for sample sizes"],"tags":["apache-beam","combiners","argument-validation"],"backgroundTag":"value-out-of-range","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}