What causes "illegal iter type: %v" in apache/beam?

Change the DoFn parameter to a supported iterator type: func(v T) bool or the beam counterparts funcx recognizes.

illegal iter type: %v

Error message

illegal iter type: %v

What it means

makeIter adapts a ReStream into a reflection function value for side inputs / DoFn iterators. It only supports types that funcx.UnfoldIter can decompose into (element-type) iterator signatures; anything else — a non-function type or an unsupported signature — panics with the offending type.

Source

Thrown at sdks/go/pkg/beam/core/runtime/exec/input.go:122

	// cur is the "current" stream, if any.
	cur Stream
}

func makeIter(t reflect.Type, s ReStream) ReusableInput {
	inputsMu.Lock()
	maker, exists := inputs[t]
	inputsMu.Unlock()

	if exists {
		return maker(s)
	}

	// If no specialized implementation is available, we use the (slower)
	// reflection-based one.

	types, ok := funcx.UnfoldIter(t)
	if !ok {
		panic(fmt.Sprintf("illegal iter type: %v", t))
	}

	ret := &iterValue{types: types, s: s}
	ret.fn = reflect.MakeFunc(t, ret.invoke).Interface()
	return ret
}

func (v *iterValue) Init() error {
	cur, err := v.s.Open()
	if err != nil {
		return err
	}
	v.cur = cur
	return nil
}

func (v *iterValue) Value() any {
	return v.fn

View on GitHub (pinned to 12126d8942)

Solutions

Change the DoFn parameter to a supported iterator type: func(v T) bool or the beam counterparts funcx recognizes.
Verify the side input's element type matches the iterator's element type in the pipeline graph.
Guard construction by calling funcx.UnfoldIter yourself first and reporting a clear configuration error.

Example fix

// before
func (d *myFn) ProcessElement(s map[string]int, v string) { ... } // unsupported side input type
// after
func (d *myFn) ProcessElement(kv func(func(KV[string,int]) bool), v string) { ... }

Defensive patterns

Strategy: type-guard

Validate before calling

if _, ok := funcx.UnfoldIter(t); !ok {
	return fmt.Errorf("side input type %v is not a supported iterator", t)
}

Type guard

func usableIter(t reflect.Type) bool { _, ok := funcx.UnfoldIter(t); return ok }

Prevention

Declare DoFn iterator parameters as func(v T) bool style types funcx supports.
Ensure side-input element types in the graph match the DoFn parameter's element type.
Run a small smoke-test pipeline with the side input before deploying.

When it happens

Trigger: makeSideInput or invoke paths call makeIter with a type t for which UnfoldIter returns ok=false, e.g. the parameter type isn't func(T) bool / func(*T) bool shaped.

Common situations: Declaring a DoFn side-input parameter with a wrong type (slice, channel, or wrong function signature), graph/coder mismatch between pipeline submission and execution, or API misuse building custom inputs.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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