{"record":{"id":"b5898eeac6a65c42","repo":"apache/beam","slug":"if-num-buckets-is-set-it-has-to-be-an-integer-greater-than-0","errorCode":null,"errorMessage":"If `num_buckets` is set, it has to be an integer greater than 0, got %s","messagePattern":"If `num_buckets` is set, it has to be an integer greater than 0, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/util.py","lineNumber":1624,"sourceCode":"  transforms.\n\n  Reshuffle adds a temporary random key to each element, performs a\n  ReshufflePerKey, and finally removes the temporary key.\n  \"\"\"\n\n  # We use 32-bit integer as the default number of buckets.\n  _DEFAULT_NUM_BUCKETS = 1 << 32\n\n  def __init__(self, num_buckets=None):\n    \"\"\"\n    :param num_buckets: If set, specifies the maximum random keys that would be\n      generated.\n    \"\"\"\n    self.num_buckets = num_buckets if num_buckets else self._DEFAULT_NUM_BUCKETS\n\n    valid_buckets = isinstance(num_buckets, int) and num_buckets > 0\n    if not (num_buckets is None or valid_buckets):\n      raise ValueError(\n          'If `num_buckets` is set, it has to be an '\n          'integer greater than 0, got %s' % num_buckets)\n\n  def expand(self, pcoll):\n    # type: (pvalue.PValue) -> pvalue.PCollection\n    if pcoll.pipeline.options.is_compat_version_prior_to(\n        RESHUFFLE_TYPEHINT_BREAKING_CHANGE_VERSION):\n      reshuffle_step = ReshufflePerKey()\n    else:\n      reshuffle_step = ReshufflePerKey().with_input_types(\n          tuple[int, T]).with_output_types(tuple[int, T])\n    return (\n        pcoll | 'AddRandomKeys' >>\n        Map(lambda t: (random.randrange(0, self.num_buckets), t)\n            ).with_input_types(T).with_output_types(tuple[int, T])\n        | reshuffle_step\n        | 'RemoveRandomKeys' >> Map(lambda t: t[1]).with_input_types(\n            tuple[int, T]).with_output_types(T))","sourceCodeStart":1606,"sourceCodeEnd":1642,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/util.py#L1606-L1642","documentation":"ApproximateUnique (and similar sampling transforms) validate num_buckets: it must be None (use the default) or a positive integer; anything else raises ValueError with the supplied value. Note the constructor first coerces falsy values (0) to the default, but explicit bad values like negatives or non-ints are rejected.","triggerScenarios":"Calling ApproximateUnique(num_buckets=-5), num_buckets=2.5, num_buckets='1000', or num_buckets=0 handled specially but e.g. False; also passing num_buckets alongside size when they conflict in downstream validation.","commonSituations":"Copy-pasting size values into num_buckets; passing a string from YAML/CLI without int(); using 0 expecting 'auto' when 0 actually becomes the default via falsy coercion but other invalid values raise.","solutions":["Pass num_buckets as a positive int (larger for better accuracy) or omit it entirely","If reading from config/CLI, convert: num_buckets = int(raw) and check > 0","Prefer specifying size (target error) and let num_buckets default"],"exampleFix":"// before\nApproximateUnique(num_buckets='1000')\n// after\nApproximateUnique(num_buckets=int(config_num_buckets) if config_num_buckets else None)","handlingStrategy":"validation","validationCode":"if num_buckets is not None and not (isinstance(num_buckets, int) and num_buckets > 0):\n    raise ValueError('num_buckets must be a positive int or None')","typeGuard":"def valid_buckets(v): return v is None or (isinstance(v, int) and not isinstance(v, bool) and v > 0)","tryCatchPattern":null,"preventionTips":["Convert config strings to int before passing","Prefer specifying size (error bound) over num_buckets","Test transform construction with representative config values"],"tags":["python","apache-beam","validation","constructor","approximation"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}