apache/beam · error

errIllegalParametersInMultiMap

Error message

errIllegalParametersInMultiMap

What it means

unfoldMultiMap in sdks/go/pkg/beam/core/funcx/sideinput.go validates keyed multimap iterator functions, which must take exactly 1 input (the key) and return exactly 1 output that is itself a valid iterator generator. The output is validated via unfoldIter and any resulting error is wrapped with errIllegalParametersInMultiMap. The library throws it to attribute the signature failure to the multimap function.

Source

Thrown at sdks/go/pkg/beam/core/funcx/sideinput.go:188

// UnfoldMultiMap returns the parameter types for the input key and the output
// values iff the type is a keyed functional iterator generator.
func UnfoldMultiMap(t reflect.Type) ([]reflect.Type, bool) {
	types, ok, _ := unfoldMultiMap(t)
	return types, ok
}

func unfoldMultiMap(t reflect.Type) ([]reflect.Type, bool, error) {
	if t.Kind() != reflect.Func {
		return nil, false, nil
	}
	if t.NumIn() != 1 || t.NumOut() != 1 {
		return nil, false, nil
	}
	types := []reflect.Type{t.In(0)}
	iterTypes, is, err := unfoldIter(t.Out(0))
	types = append(types, iterTypes...)
	return types, is, errors.Wrap(err, errIllegalParametersInMultiMap)
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Use the exact shape `func(k K) func(*V) bool` with exactly one key input and one iterator-generator output.
2. Fix the inner iterator parameters (pointer to a valid PCollection element type) since the wrapped error originates in unfoldIter.
3. Confirm the signature with fx.IsMultiMap / fx.IsMalformedMultiMap in a test.

Example fix

// before
mm := func(k string) *int { ... }
// after
mm := func(k string) func(*int) bool {
	vals := ... // values for key k
	return func(v *int) bool { ... }
}

func checkMultiMap(fn interface{}) error {
	t := reflect.TypeOf(fn)
	if t == nil || t.Kind() != reflect.Func {
		return fmt.Errorf("not a func: %T", fn)
	}
	if t.NumIn() != 1 || t.NumOut() != 1 {
		return fmt.Errorf("multimap must have 1 in, 1 out; got %d in, %d out", t.NumIn(), t.NumOut())
	}
	out := t.Out(0)
	if out.Kind() != reflect.Func {
		return fmt.Errorf("multimap output must be a func, got %v", out)
	}
	for i := 0; i < out.NumIn(); i++ {
		if out.In(i).Kind() != reflect.Ptr {
			return fmt.Errorf("inner value param %d must be a pointer", i)
		}
	}
	return nil
}

func isMultiMapShape(t reflect.Type) bool {
	return t != nil && t.Kind() == reflect.Func && t.NumIn() == 1 && t.NumOut() == 1 && t.Out(0).Kind() == reflect.Func
}

if _, ok, err := fx.UnfoldMultiMap(fn); err != nil {
	// err wraps errIllegalParametersInMultiMap
	return fmt.Errorf("bad multimap signature: %w", err)
}

When it happens

Trigger: Providing a multimap function like `func(k string) *int` (output is not an iterator generator) or `func(k string) func(v int) bool` where the inner value parameter is not a pointer, causing the wrapped unfoldIter error.

Common situations: Using PCollectionView<KV<K, Iterable<V>>>-style side inputs in Go and mis-declaring the accessor function; forgetting the pointer on the value parameter of the inner iterator; giving the function zero or multiple key parameters.

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

• errIllegalParametersInIter
• errIllegalParametersInReIter
• Iterators with timestamp values (<ET,V> and <ET, K, V>) are
• Type interface{} isn't a supported PCollection type
• failed to map main input window to side input window with Wi

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