{"record":{"id":"cb5a3b17eafdc844","repo":"apache/beam","slug":"partitionfn-specified-out-of-bounds-partition-index-d-not-in","errorCode":null,"errorMessage":"PartitionFn specified out-of-bounds partition index: %d not in [0, %d)","messagePattern":"PartitionFn specified out-of-bounds partition index: (.+?) not in \\[0, (.+?)\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/core.py","lineNumber":3836,"sourceCode":"    partitionfn: a PartitionFn, or a callable with the signature described in\n      CallableWrapperPartitionFn.\n    n: number of output partitions.\n\n  The result of this PTransform is a simple list of the output PCollections\n  representing each of n partitions, in order.\n  \"\"\"\n  class ApplyPartitionFnFn(DoFn):\n    \"\"\"A DoFn that applies a PartitionFn.\"\"\"\n    def process(self, element, partitionfn, n, *args, **kwargs):\n      partition = partitionfn.partition_for(element, n, *args, **kwargs)\n      import numbers\n      if isinstance(partition,\n                    bool) or not isinstance(partition, numbers.Integral):\n        raise ValueError(\n            f\"PartitionFn yielded a '{type(partition).__name__}' \"\n            \"when it should only yield integers\")\n      if not 0 <= int(partition) < n:\n        raise ValueError(\n            'PartitionFn specified out-of-bounds partition index: '\n            '%d not in [0, %d)' % (partition, n))\n      # Each input is directed into the output that corresponds to the\n      # selected partition.\n      yield pvalue.TaggedOutput(str(partition), element)\n\n  def make_fn(self, fn, has_side_inputs):\n    return fn if isinstance(fn, PartitionFn) else CallableWrapperPartitionFn(fn)\n\n  def expand(self, pcoll):\n    n = int(self.args[0])\n    args, kwargs = util.insert_values_in_args(\n        self.args, self.kwargs, self.side_inputs)\n    return pcoll | ParDo(self.ApplyPartitionFnFn(), self.fn, *args, **\n                         kwargs).with_outputs(*[str(t) for t in range(n)])\n\n\nclass Windowing(object):","sourceCodeStart":3818,"sourceCodeEnd":3854,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/core.py#L3818-L3854","documentation":"Raised inside Partition's DoFn after the type check: the PartitionFn returned an integer, but its value is outside the valid range [0, n), where n is the number of output partitions. Beam routes each element to a tagged output named str(partition), so out-of-range indices cannot be delivered. The error reports the offending index and the valid bound.","triggerScenarios":"partition_for returns hash(x) % m where m != n; using a hard-coded partition index like return 3 while constructing beam.Partition(2); computing an index from data whose cardinality exceeds the configured partition count; negative indices from modulo of negative hashes in other languages.","commonSituations":"Changing the number of partitions in the pipeline (beam.Partition(fn, 3)) without updating a hard-coded PartitionFn; using element values directly as indices; stale constants after refactoring partition count.","solutions":["Always compute the index modulo n: return value % n (with a non-negative base).","Match hard-coded indices to the partition count passed to beam.Partition().","Clamp or validate: index = min(max(0, computed), n - 1) if clamping is semantically OK.","Pass the partition count into the PartitionFn configuration rather than duplicating constants."],"exampleFix":"// before\nmy_partition = pc | beam.Partition(lambda x, n: x.bucket, 3)  # bucket can be 0..9\n// after\nmy_partition = pc | beam.Partition(lambda x, n: x.bucket % n, 3)","handlingStrategy":"validation","validationCode":"idx = partitionfn.partition_for(elem, n)\nassert 0 <= int(idx) < n, f'partition {idx} out of range [0, {n})'","typeGuard":null,"tryCatchPattern":"try:\n    pc | beam.Partition(fn, n)\nexcept ValueError as e:\n    log.error('Out-of-bounds partition: %s', e)","preventionTips":["Always modulo by n: value % n","Derive partition count from one shared constant","Unit-test partition_for with edge elements","Avoid hard-coded indices"],"tags":["python","apache-beam","partitionfn","value-out-of-range"],"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"}