apache/beam · error

partitionFn(%v) = %v, want [0,%v)

Error message

partitionFn(%v) = %v, want [0,%v)

What it means

This error is returned by the DoFn wrapper partitionFn.Call when a user's partition function returns an index outside the valid range [0, n), where n is the number of output partitions declared for the Partition transform. The Beam Go SDK validates the index before dispatching the element to the corresponding emitter, because an out-of-range index has no matching output channel. The error carries the element value, the bad index, and the expected bound so the user can debug their function.

Source

Thrown at sdks/go/pkg/beam/partition.go:128

	n    int
	fn   reflectx.Func1x1
}

func (f *partitionFn) Name() string {
	return f.name
}

func (f *partitionFn) Type() reflect.Type {
	return f.t
}

func (f *partitionFn) Call(args []any) []any {
	timestamp := args[0]
	value := args[1]

	n := f.fn.Call1x1(value).(int)
	if n < 0 || n >= f.n {
		return []any{errors.Errorf("partitionFn(%v) = %v, want [0,%v)", value, n, f.n)}
	}

	emit := args[n+2]
	reflectx.MakeFunc2x0(emit).Call2x0(timestamp, value)

	var err error
	return []any{err}
}

// partitionFnKV is a Func with the following underlying type:
//
//	fn : (EventTime, K, V, emit_1, emit_2, ..., emit_N) -> error
//
// where emit_i : (EventTime, K, V) -> () and N is given by the encoded
// partitionData value. For any input element, it invokes to the
// given partition function to determine which emitter to use.
type partitionFnKV struct {
	name string

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the partition function so it always returns an index in [0, n), e.g. clamp or modulo the result
2. Verify the number of partitions passed to beam.Partition matches the function's possible return values
3. Check the element that triggered the failure and add a guard/default branch in the function for edge-case inputs
4. Log or unit-test the partition function over representative elements before submitting the pipeline

Example fix

// before
func partition(v string) int {
  return len(v) // can exceed n
}
// after
func partition(v string) int {
  i := len(v) % 3
  if i < 0 { i = 0 }
  return i
}

n := partitionFn(value)
if n < 0 || n >= numPartitions {
    return fmt.Errorf("partition index %d out of range [0,%d) for value %v", n, numPartitions, value)
}

if err := beam.Partition(s, numPartitions, fn, input); err != nil {
    log.Fatalf("partition fn out of range: %v", err)
}

When it happens

Trigger: Calling partitionFn.Call when the user-supplied partition function (invoked via f.fn.Call1x1(value)) returns a negative int or an int >= f.n for a given element.

Common situations: A partition function computing an index from data (e.g. len(s) % n written as len(s) itself, or dividing by zero leading to odd results), off-by-one errors like returning n for the 'last' bucket, or a function whose return type accidentally coerces to an unexpected int.

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

• n must be > 0
• encoding partition function
• unmarshalling partitionFn data
• max_insert_payload_size can only go up to 10485760 bytes, as
• Split fraction must be within the range [0,1]

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