apache/beam · error

errIllegalParametersInIter

Error message

errIllegalParametersInIter

What it means

unfoldIter in sdks/go/pkg/beam/core/funcx/sideinput.go validates that a function used as an iterator side input has only parameters that are valid pointer side-input types. After the arity guard (0, 1, or 2 params beyond skip), every remaining parameter is checked with isOutParam; if any parameter is not a pointer to a universal/container/concrete PCollection type, the underlying error is wrapped with errIllegalParametersInIter and returned. The library throws it because iterator side inputs are mechanically unfolded from the function's reflect.Type, and a non-pointer parameter cannot back a PCollection iterator.

Source

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

	if t.NumOut() != 1 || t.Out(0) != reflectx.Bool {
		return nil, false, nil
	}
	if t.NumIn() == 0 {
		return nil, false, nil
	}

	var ret []reflect.Type
	skip := 0
	if t.In(0).Kind() == reflect.Ptr && t.In(0).Elem() == typex.EventTimeType {
		return nil, false, errors.New(errIllegalEventTimeInIter)
	}
	if t.NumIn()-skip > 2 || t.NumIn() == skip {
		return nil, false, nil
	}

	for i := skip; i < t.NumIn(); i++ {
		if ok, err := isOutParam(t.In(i)); !ok {
			return nil, false, errors.Wrap(err, errIllegalParametersInIter)
		}
		if reflect.TypeOf((*any)(nil)).Elem() == t.In(i).Elem() && !typex.IsUniversal(t.In(i)) {
			return nil, false, errors.New("Type interface{} isn't a supported PCollection type")
		}
		ret = append(ret, t.In(i).Elem())
	}
	return ret, true, nil
}

func isOutParam(t reflect.Type) (bool, error) {
	if t.Kind() != reflect.Ptr {
		return false, errors.Errorf("Type %v of kind %v not allowed, must be ptr type", t, t.Kind())
	}
	if typex.IsUniversal(t.Elem()) || typex.IsContainer(t.Elem()) {
		return true, nil
	}
	return typex.CheckConcrete(t.Elem())
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Change each side-input parameter to a pointer to a valid PCollection element type, e.g. `func(i *int) bool` or `func(s *[]string)`.
2. If the parameter is `*interface{}`, replace it with a concrete typed pointer or a typex universal/container type.
3. Keep the parameter count within the allowed range (at most 2 parameters beyond the skipped context/receiver) so unfoldIter proceeds to parameter validation rather than bailing silently.
4. Call fx.IsIter(fn) or fx.IsMalformedIter(fn) in a unit test to validate the signature before running the pipeline.

Example fix

// before
fn := func(ctx context.Context, words []string, q string) bool { ... }
// after
fn := func(words *[]string, q *string) bool { ... }

// before registering the DoFn / side input
if err := fx.IsMalformedIter(fn); err != nil {
	return fmt.Errorf("invalid iter side-input signature for %T: %w", fn, err)
}

func isValidIterSig(fn interface{}) bool {
	t := reflect.TypeOf(fn)
	if t == nil || t.Kind() != reflect.Func {
		return false
	}
	for i := 0; i < t.NumIn(); i++ {
		if t.In(i).Kind() != reflect.Ptr {
			return false
		}
	}
	return true
}

if _, _, err := fx.UnfoldIter(fn); err != nil {
	// err wraps errIllegalParametersInIter
	return fmt.Errorf("side input rejected: %w", err)
}

When it happens

Trigger: Registering a DoFn or side-input function via funcx where a parameter (after the context/receiver skip) is not a pointer type, e.g. `func(ctx context.Context, i int)` or `func(kv KV)` passed to beam.ParDo / fx.UnfoldIter. Also triggered when a parameter is `*interface{}` (bare interface{} element) that is not a universal typex type.

Common situations: Writing a DoFn with a side input declared as a value or struct instead of a pointer (e.g. `s []string` instead of `s *[]string`); copying a Java/Python Beam side-input idiom into Go; refactoring a DoFn signature and dropping the `*`.

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

• Type %v of kind %v not allowed, must be ptr type
• errIllegalParametersInReIter
• errIllegalParametersInMultiMap
• not a function: %v
• illegal re-iter type: %v

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