invalid number of main input params in method

Error message

invalid number of main input params in method %v. got: %v, want: %v or %v

What it means

When a DoFn is registered as a Splittable DoFn (SDF), Beam Go infers the main-input shape from the signature of its CreateInitialRestriction method. The method must take exactly one element parameter (MainSingle, e.g. T) or exactly two (MainKv, e.g. K and V). If the reflected method has any other number of main input params, validateSdfSignatures (via AsDoFn) rejects the DoFn because restriction creation cannot be correlated with ProcessElement inputs.

Solutions

Change CreateInitialRestriction so its non-context parameters are exactly one element (single input) or exactly two (key and value), matching ProcessElement.
Verify the element types in CreateInitialRestriction match the element parameters of ProcessElement exactly.
Confirm the method is actually named CreateInitialRestriction and is attached to the DoFn struct so reflection finds the intended method.
If the function only needs context.Context or metadata, ensure those are not counted as main inputs — only element (and optional key) params count.

Example fix

// before
func (fn *myFn) CreateInitialRestriction(ctx context.Context, elem string, opts Options) myRestriction { ... }

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

Defensive patterns

Strategy: validation

Validate before calling

// Ensure CreateInitialRestriction's main-input shape before registration:
func checkSdfMainInput(fn any) error {
    m := reflect.TypeOf(fn).MethodByName("CreateInitialRestriction")
    if !m.IsValid { /* handle */ }
    n := m.Type.NumIn() - 1 // minus receiver
    if n == 1 || n == 2 { return nil }
    return fmt.Errorf("CreateInitialRestriction must have 1 or 2 main-input params, got %d", n)
}

Prevention

Copy a known-good SDF signature template when writing new SDFs
Keep CreateInitialRestriction and ProcessElement element types defined once and reused
Compile-time assertion helpers from beam docs to validate SDF shapes early

When it happens

Trigger: Registering a DoFn with beam.TrySdf/beam.Sdf where CreateInitialRestriction declares zero main-input params, three or more main-input params, or params Beam cannot map to ProcessElement's element (or key/value) parameters.

Common situations: Hand-written SDFs where CreateInitialRestriction was given extra context or options parameters as main inputs; refactoring ProcessElement from single element to KV (or vice versa) without updating CreateInitialRestriction; porting a Java SDF whose method signatures don't translate to the Go SDK's two allowed shapes.

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

Appendix: source

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

// consistent with each other (for example, element and restriction types should
// match with each other). Returns an error if one is found, or nil if the
// types are all valid.
// TODO(BEAM-3301): Once SDF documentation is added to ParDo, add a comment
// here to refer to that for specific details about what needs to be consistent.
func validateSdfSignatures(fn *Fn, numMainIn mainInputs) error {
	num := int(numMainIn)

	// If number of main inputs is ambiguous, we check for consistency against
	// CreateInitialRestriction.
	if numMainIn == MainUnknown {
		initialRestFn := fn.methods[createInitialRestrictionName]
		paramNum := len(initialRestFn.Params(funcx.FnValue))

		switch paramNum {
		case int(MainSingle), int(MainKv):
			num = paramNum
		default: // Can't infer because method has invalid # of main inputs.
			err := errors.Errorf("invalid number of main input params in method %v. got: %v, want: %v or %v",
				createInitialRestrictionName, paramNum, int(MainSingle), int(MainKv))
			return errors.SetTopLevelMsgf(err, "Invalid number of main input parameters in method %v. "+
				"Got: %v, Want: %v or %v. Check that the signature conforms to the expected signature for %v, "+
				"and that elements in SDF method parameters match elements in %v.",
				createInitialRestrictionName, paramNum, int(MainSingle), int(MainKv), createInitialRestrictionName, processElementName)
		}
	}

	if err := validateSdfSigNumbers(fn, num); err != nil {
		return err
	}
	if err := validateSdfSigTypes(fn, num); err != nil {
		return err
	}

	return nil
}

View on GitHub (pinned to 12126d8942)