unexpected number of elements returned in method

Error message

unexpected number of elements returned in method %v. got: %v, want %v. Check that the signature conforms to the expected signature for %v.

What it means

In a stateful SDF, WatermarkEstimatorState must return exactly one value: the current watermark state extracted from the estimator. Beam validates len(method.Ret) == 1 and throws this error when the method returns zero values or multiple return values (e.g. also returning an error, which this signature does not allow).

Solutions

Change WatermarkEstimatorState to return exactly one value of the state type; handle errors inside or in RunWatermarkEstimator, which does return an error.
If you need to signal failure, return a zero-value/failed state or handle it in RunWatermarkEstimator.
Confirm you modified WatermarkEstimatorState and not another similarly named method.
Check the documented signature table for stateful SDF watermark methods.

Example fix

// before
func (f *fn) WatermarkEstimatorState(we sdf.WatermarkEstimator) (myState, error) {
    s, err := extract(we)
    return s, err
}
// after
func (f *fn) WatermarkEstimatorState(we sdf.WatermarkEstimator) myState {
    return we.(*myWatermarkEstimator).state
}

Defensive patterns

Strategy: validation

Validate before calling

var _ func(sdf.WatermarkEstimator) myState = (*fn).WatermarkEstimatorState

Prevention

Remember WatermarkEstimatorState returns a single value, no error.
Handle errors in RunWatermarkEstimator, which is the only watermark method returning error.
Use a function-signature assertion to lock the return arity.

When it happens

Trigger: Declaring WatermarkEstimatorState(we sdf.WatermarkEstimator) (myState, error) or with no return value; returning extra metadata alongside the state.

Common situations: Adding an error return out of Go habit since most other DoFn methods return errors; refactoring to also return the estimator; following a stateless SDF pattern in a stateful one.

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/efd153f5e2ce94ec. Report an issue: GitHub.

Appendix: source

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

					initialWatermarkEstimatorStateName, 0, method.Param[0].T, typex.EventTimeType)
				return errors.SetTopLevelMsgf(err, "mismatched event time type in method %v, "+
					"parameter at index %v. got: %v, want: %v.",
					initialWatermarkEstimatorStateName, 0, method.Param[0].T, typex.EventTimeType)
			}
			if method.Param[1].T != restT {
				err := errors.Errorf("mismatched restriction type in method %v, param %v. got: %v, want: %v",
					initialWatermarkEstimatorStateName, 1, method.Param[1].T, restT)
				return errors.SetTopLevelMsgf(err, "mismatched restriction type in method %v, "+
					"parameter at index %v. got: %v, want: %v (from method %v). "+
					"Ensure that all restrictions in an SDF are the same type.",
					initialWatermarkEstimatorStateName, 1, method.Param[1].T, restT, createTrackerName)
			}
			if err := validateSdfElementT(fn, initialWatermarkEstimatorStateName, method, numMainIn, 2); err != nil {
				return err
			}

			if len(method.Ret) != 1 {
				err := errors.Errorf("unexpected number of elements returned in method %v. got: %v, want %v",
					initialWatermarkEstimatorStateName, len(method.Ret), 1)
				return errors.SetTopLevelMsgf(err, "unexpected number of elements returned in method %v. "+
					"got: %v, want %v. Check that the signature conforms to the expected signature for %v.",
					initialWatermarkEstimatorStateName, len(method.Ret), 1, initialWatermarkEstimatorStateName)
			}
			if method.Ret[0].T != watermarkStateT {
				err := errors.Errorf("mismatched output type in method %v, return %v. got: %v, want: %v",
					createWatermarkEstimatorName, 0, method.Ret[0].T, watermarkStateT)
				return errors.SetTopLevelMsgf(err, "mismatched output type in method %v, "+
					"return value at index %v got: %v, want: %v (from method %v). "+
					"Ensure that all watermark states in an SDF are the same type.",
					createWatermarkEstimatorName, 0, method.Ret[0].T, watermarkStateT, createWatermarkEstimatorName)
			}
		case watermarkEstimatorStateName:
			if len(method.Param) != 1 {
				err := errors.Errorf("unexpected number of params in method %v. got: %v, want %v",
					watermarkEstimatorStateName, len(method.Param), 1)
				return errors.SetTopLevelMsgf(err, "unexpected number of parameters in method %v. "+

View on GitHub (pinned to 12126d8942)