apache/beam · error

failed to match optional parameter %v

Error message

failed to match optional parameter %v

What it means

matchOpt walks the function's optional parameters in order, matching each against the signature's optional model list. This error is returned when an optional parameter's type does not appear anywhere (further) in the model list, i.e. the function has an optional parameter the signature does not offer.

Source

Thrown at sdks/go/pkg/beam/core/funcx/signature.go:223

}

func matchOpt(list, models []reflect.Type, m map[string]reflect.Type) error {
	i := 0
	for _, t := range list {
		if typex.IsUniversal(t) {
			// Substitute optional types, if bound.
			subst, ok := m[t.Name()]
			if !ok {
				return errors.Errorf("optional generic parameter not bound %v", t.Name())
			}
			t = subst
		}
		for i < len(models) && models[i] != t {
			i++
		}

		if i == len(models) {
			return errors.Errorf("failed to match optional parameter %v", t)
		}
	}
	return nil
}

// MustSatisfy panics if the given fn does not satisfy the signature.
func MustSatisfy(fn any, sig *Signature) {
	if err := Satisfy(fn, sig); err != nil {
		panic(errors.Wrapf(err, "fn does not satisfy signature %v", sig))
	}
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Remove the unmatched optional parameter from the function.
2. Add the corresponding optional model to sig.OptArgs/OptReturn in the same order.
3. Reorder the function's parameters to match the signature's optional model ordering.

Example fix

// before
func (fn *doFn) ProcessElement(ctx context.Context, evt T, emit func(T), side SideIn) // 'side' not in OptArgs
// after
func (fn *doFn) ProcessElement(ctx context.Context, evt T, emit func(T))

for i, opt := range fnOptionalParams(fn) {
    if i >= len(sig.OptArgs) || !matchesModel(opt, sig.OptArgs[i]) {
        return fmt.Errorf("optional param %v not offered by sig %v", opt, sig)
    }
}

When it happens

Trigger: Calling Satisfy with a function whose optional parameter type (after generic substitution) is not in sig.OptArgs/OptReturn models, e.g. a DoFn method taking an extra optional emit<X> that the signature's optional list lacks.

Common situations: Adding an optional context/counter/emitter parameter to a DoFn method without updating the Signature; wrong parameter order so matching runs past the available models; a signature built for a different variant of the function.

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

• not enough required parameters: %v
• too many parameters: %v
• first main input parameter must be a value type
• inferCoder failed: interface type %v has no coder registered
• errIllegalParametersInIter

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