CreateInitialRestriction has unexpected number of return…

Error message

CreateInitialRestriction has unexpected number of return values: %v

What it means

The Beam Go SDK's reflection-based invoker for the splittable DoFn (SDF) method CreateInitialRestriction validates the signature's return arity at call time. A valid DoFn must return either just the restriction, or (restriction, error). Any other number of return values triggers this panic, because the runtime cannot map the reflection results onto the expected contract.

Solutions

Change CreateInitialRestriction to return exactly one value: the restriction (e.g. (MyRestriction))
Or return two values: (MyRestriction, error) if the method can fail
Check the sdf package docs for the exact permitted signatures for your element type
Run the pipeline's local (direct) validation/tests before submitting to a runner

Example fix

// before
func (fn *MyDoFn) CreateInitialRestriction(elem string) (MyRestriction, int, error) { ... }
// after
func (fn *MyDoFn) CreateInitialRestriction(elem string) MyRestriction { ... }

Defensive patterns

Strategy: validation

Validate before calling

t := reflect.TypeOf(fn.CreateInitialRestriction)
if t.NumOut() != 1 && t.NumOut() != 2 {
    panic("CreateInitialRestriction must return (R) or (R, error)")
}

Type guard

func validArity(m interface{}) bool {
    n := reflect.TypeOf(m).NumOut()
    return n == 1 || n == 2
}

Prevention

Copy signatures verbatim from the sdf package docs/examples
Add compile-time interface assertions for your DoFn
Run DoFn signature validation tests locally before submitting pipelines
Never add extra return values for logging/diagnostics to SDF lifecycle methods

When it happens

Trigger: Defining a DoFn method CreateInitialRestriction with 0, or 3+ return values; wrong method wiring where the reflected call returns a mismatched result set (e.g. signature registered against the wrong method type).

Common situations: Hand-writing SDF methods instead of following the documented signatures; copy-paste refactors that changed return types; mixing up CreateInitialRestriction with a different SDF lifecycle method's signature.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/exec/sdf_invokers_arity.go:87

			return r0, asError(r1)
		}

	default:
		if len(n.fn.Param) < 1 || len(n.fn.Param) > 3 {
			return errors.Errorf("CreateInitialRestriction has unexpected number of parameters: %v", len(n.fn.Param))
		}

		n.call = func() (rest any, err error) {
			ret := n.fn.Fn.Call(n.args)

			switch len(ret) {
			case 1:
				return ret[0], nil
			case 2:
				return ret[0], asError(ret[1])
			}

			panic(fmt.Sprintf("CreateInitialRestriction has unexpected number of return values: %v", len(ret)))
		}
	}

	return nil
}

func (n *srInvoker) initCallFn() error {
	// Expects a signature of the form:
	// (context.Context?, key?, value, restriction) ([]restriction, error?)
	// TODO(BEAM-9643): Link to full documentation.
	switch fnT := n.fn.Fn.(type) {

	case reflectx.Func2x1:
		n.call = func() (splits any, err error) {
			r0 := fnT.Call2x1(n.args[0], n.args[1])
			return r0, nil
		}

View on GitHub (pinned to 12126d8942)