CreateInitialRestriction has unexpected number of parameters

Error message

CreateInitialRestriction has unexpected number of parameters: %v

What it means

The CreateInitialRestriction function of an SDF must take between 1 and 3 parameters (element, and optionally timestamp and/or restriction-related inputs). initCallFn in sdf_invokers_arity.go rejects any other arity with this error during invoker setup. Fast-path implementations exist for common arities; anything else falls to the default validation.

Source

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

			r0, r1 := fnT.Call1x2(n.args[0])
			return r0, asError(r1)
		}

	case reflectx.Func2x2:
		n.call = func() (rest any, err error) {
			r0, r1 := fnT.Call2x2(n.args[0], n.args[1])
			return r0, asError(r1)
		}

	case reflectx.Func3x2:
		n.call = func() (rest any, err error) {
			r0, r1 := fnT.Call3x2(n.args[0], n.args[1], n.args[2])
			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
}

View on GitHub (pinned to 12126d8942)

Solutions

Give CreateInitialRestriction 1-3 parameters, typically func(el T) R (optionally + typex.EventTime, + a second input).
Remove unsupported parameters such as context.Context from the signature.
Capture needed configuration in the DoFn struct rather than via extra parameters.
Check the signature against the sdf package's documented CreateInitialRestriction forms.

Example fix

// before
func (fn *mySdf) CreateInitialRestriction(ctx context.Context, el string) watermarksInterval { ... }
// after
func (fn *mySdf) CreateInitialRestriction(el string) watermarksInterval { ... }

Defensive patterns

Strategy: validation

Validate before calling

t := reflect.TypeOf(fn.CreateInitialRestriction)
n := t.NumIn()
if n < 1 || n > 3 {
    return fmt.Errorf("CreateInitialRestriction must take 1-3 parameters, has %d", n)
}

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "CreateInitialRestriction has unexpected number of parameters") {
        // fix arity to 1-3
    }
    return err
}

Prevention

Use func(el T) R as the canonical CreateInitialRestriction shape.
Never add context.Context to SDF lifecycle hooks unless documented.
Match parameter lists across CreateInitialRestriction/SplitRestriction/RestrictionSize.

When it happens

Trigger: Registering a CreateInitialRestriction fn with 0 parameters or 4+ parameters, e.g. func() R or func(ctx context.Context, el T, ts typex.EventTime, w W) R. Raised by newCreateInitialRestrictionInvoker when building the DoFn's reflection invoker.

Common situations: Adding a context.Context first parameter (not supported for this hook), or defining the method with no parameters at all, usually after refactoring a DoFn.

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