apache/beam · error

n must be > 0

Error message

n must be > 0

What it means

top.Smallest, top.Largest and their PerKey variants call validate, which panics if n (the number of top elements to keep) is less than 1. n must be a positive integer; the transform cannot produce 'top 0' results.

Source

Thrown at sdks/go/pkg/beam/transforms/top/top.go:103

	return beam.Combine(s, newCombineFn(less, n, t.Type(), true), col)
}

// SmallestPerKey returns the smallest N values for each key of a PCollection<KV<K,T>>.
// The order is defined by the comparator, less : T x T -> bool. It returns a
// PCollection<KV<K,[]T>> with a slice of the N smallest elements for each key.
func SmallestPerKey(s beam.Scope, col beam.PCollection, n int, less any) beam.PCollection {
	s = s.Scope(fmt.Sprintf("top.SmallestPerKey(%v)", n))

	_, t := beam.ValidateKVType(col)
	validate(t, n, less)

	return beam.CombinePerKey(s, newCombineFn(less, n, t.Type(), true), col)
}

func validate(t typex.FullType, n int, less any) {
	if n < 1 {
		panic("n must be > 0")
	}
	funcx.MustSatisfy(less, funcx.Replace(sig, beam.TType, t.Type()))
}

func newCombineFn(less any, n int, t reflect.Type, reversed bool) *combineFn {
	fn := &combineFn{Less: beam.EncodedFunc{Fn: reflectx.MakeFunc(less)}, N: n, Type: beam.EncodedType{T: t}, Reversed: reversed}
	// Running SetupFn at pipeline construction helps validate the
	// combineFn, and simplify testing.
	fn.Setup()
	return fn
}

// TODO(herohde) 5/25/2017: use a heap instead of a sorted slice.

type accum struct {
	enc beam.ElementEncoder
	dec beam.ElementDecoder

View on GitHub (pinned to 12126d8942)

Solutions

1. Validate n >= 1 at your pipeline's configuration boundary before constructing the transform.
2. Default an unset topN config to a sensible positive value (e.g. 10).
3. Clamp with a helper like max(1, n) if zero should mean 'no limit' in your domain.

Example fix

// before
n := cfg.TopN // 0 when unset
top.Largest(s, col, n, less) // panics

// after
n := cfg.TopN
if n < 1 {
    n = 10
}
top.Largest(s, col, n, less)

if n < 1 {
    return fmt.Errorf("top.*: n must be >= 1, got %d", n)
}

When it happens

Trigger: Calling top.Largest(s, col, n, less) or top.Smallest / LargestPerKey / SmallestPerKey with n = 0 or a negative n, e.g. when n comes from an unset config variable defaulting to 0.

Common situations: A limit/topN config field left at its zero value; computing n from user input or a query parameter without validation; an off-by-one where a caller passes a count minus one.

Related errors

• trigger.AfterCount(%v) must be a positive integer
• n must be > 0
• can't apply processing delay of less than a millisecond. Got
• can't apply an alignment period of less than a millisecond.
• GroupIntoBatches: %w

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