unexpected number of returns in method %v. got: %v, want: %v

Error message

unexpected number of returns in method %v. got: %v, want: %v or optionally %v if last value is of type error

What it means

validateSdfSigNumbers also validates return-value counts for SDF methods: each method must return the required number of values, optionally plus a trailing error. This error is thrown when method.Ret has neither reqReturnNum nor reqReturnNum+1 values where the extra last value is of type error.

Source

Thrown at sdks/go/pkg/beam/core/graph/fn.go:965

	for _, name := range sdfNames {
		method, ok := fn.methods[name]
		if !ok && optionalSdfs[name] {
			continue
		}

		reqParamNum := reqParamNums[name]
		if !sdfHasValidParamNum(method.Param, reqParamNum) {
			err := errors.Errorf("unexpected number of params in method %v. got: %v, want: %v or optionally %v "+
				"if first param is of type context.Context", name, len(method.Param), reqParamNum, reqParamNum+1)
			return errors.SetTopLevelMsgf(err, "Unexpected number of parameters in method %v. "+
				"Got: %v, Want: %v or optionally %v if first param is of type context.Context. "+
				"Check that the signature conforms to the expected signature for %v, and that elements in SDF method "+
				"parameters match elements in %v.", name, len(method.Param), reqParamNum, reqParamNum+1,
				name, processElementName)
		}
		if !sdfHasValidReturnNum(method.Ret, reqReturnNum) {
			err := errors.Errorf("unexpected number of returns in method %v. got: %v, want: %v or optionally %v "+
				"if last value is of type error", name, len(method.Ret), reqReturnNum, reqReturnNum+1)
			return errors.SetTopLevelMsgf(err, "Unexpected number of return values in method %v. "+
				"Got: %v, Want: %v or optionally %v if last value is of type error. "+
				"Check that the signature conforms to the expected signature for %v.",
				name, len(method.Ret), reqReturnNum, reqReturnNum+1, name)
		}
	}
	return nil
}

func sdfHasValidParamNum(params []funcx.FnParam, requiredNum int) bool {
	if len(params) == requiredNum {
		return true
	}

	return len(params) == requiredNum+1 && params[0].Kind == funcx.FnContext
}

View on GitHub (pinned to 12126d8942)

Solutions

Change the method to return exactly the required values, optionally followed by one trailing error.
For CreateInitialRestriction/SplitRestriction/CreateTracker, remove extra return values or add the missing restriction/tracker return.
If returning an error, make sure it is the LAST return value.
Consult the expected return shape for the named method (reported in the error) in sdks/go/pkg/beam/core/graph/fn.go.

Example fix

// before
func (fn *myFn) CreateInitialRestriction(elem string) error { ... }

// after
func (fn *myFn) CreateInitialRestriction(elem string) myRestriction { ... }

Defensive patterns

Strategy: validation

Validate before calling

// Validate return counts (allowing optional trailing error) before registration:
func checkReturnCount(t reflect.Type, name string, want int) error {
    m, ok := t.MethodByName(name)
    if !ok { return fmt.Errorf("missing method %s", name) }
    n := m.Type.NumOut()
    errT := reflect.TypeOf((*error)(nil)).Elem()
    if n == want || (n == want+1 && m.Type.Out(n-1) == errT) { return nil }
    return fmt.Errorf("%s: got %d returns, want %d (+optional trailing error)", name, n, want)
}

Prevention

Return error last, only when needed
Match each SDF method to its documented return shape
Build pipelines in tests so signature errors surface in CI

When it happens

Trigger: An SDF method returning no value when one is required (e.g. CreateInitialRestriction returning nothing), or returning two non-error values, or returning error first instead of last.

Common situations: Writing ProcessElement without returning the emitted element(s); returning a restriction plus error in CreateInitialRestriction; Go beginners adding an error return out of habit in the wrong position.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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