What causes "type must be a non-complex number: %v" in apache/beam?

Extract the numeric field you actually want to average with a ParDo before calling stats.Mean.

type must be a non-complex number

Error message

type must be a non-complex number: %v

What it means

stats.Mean, MeanPerKey and the internal combine helpers call validateNonComplexNumber to assert the element type is a number and not a complex type. If reflectx.IsNumber is false or the type is complex128/complex64, the library panics because averaging is undefined for those types.

Solutions

Extract the numeric field you actually want to average with a ParDo before calling stats.Mean.
Convert string/other encodings to float64 before averaging.
For complex data, compute real/imaginary means separately or write a custom combine function.

Example fix

// before
stats.MeanPerKey(s, keyCol, recordCol) // value is Record, not a number

// after
values := beam.ParDo(s, func(r Record) float64 { return r.Score }, recordCol)
stats.MeanPerKey(s, keyCol, values)

Defensive patterns

Strategy: validation

Validate before calling

t := reflect.TypeOf(val)
if t.Kind() == reflect.Complex64 || t.Kind() == reflect.Complex128 ||
    (t.Kind() < reflect.Int || t.Kind() > reflect.Float64) {
    return fmt.Errorf("stats.Mean needs a non-complex number, got %v", t)
}

Type guard

func isNonComplexNumber(v any) bool {
    k := reflect.TypeOf(v).Kind()
    return k >= reflect.Int && k <= reflect.Float64
}

Prevention

In MeanPerKey, double-check you pass the value column (numeric), not the key column.
Extract numeric fields from structs before averaging.
Handle complex data by splitting into real/imaginary float64 streams.

When it happens

Trigger: Calling stats.Mean(s, col) or stats.MeanPerKey(s, keyCol, valCol) where the value PCollection's element type is a string, bool, struct, or complex64/complex128.

Common situations: Averaging complex numbers from signal-processing pipelines; passing a struct holding a numeric field instead of the field itself; keys/value columns swapped in MeanPerKey so the value type is a non-numeric key type.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/transforms/stats/util.go:55

	validateNonComplexNumber(t.Type())

	// Do a pipeline-construction-time type switch to select the right
	// runtime operation.
	return beam.Combine(s, makeCombineFn(t.Type()), col)
}

func combinePerKey(s beam.Scope, makeCombineFn func(reflect.Type) any, col beam.PCollection) beam.PCollection {
	_, t := beam.ValidateKVType(col)
	validateNonComplexNumber(t.Type())

	// Do a pipeline-construction-time type switch to select the right
	// runtime operation.
	return beam.CombinePerKey(s, makeCombineFn(t.Type()), col)
}

func validateNonComplexNumber(t reflect.Type) {
	if !reflectx.IsNumber(t) || reflectx.IsComplex(t) {
		panic(fmt.Sprintf("type must be a non-complex number: %v", t))
	}
}

View on GitHub (pinned to 12126d8942)