may only have a single context.Context parameter and it must

Error message

may only have a single context.Context parameter and it must be the first parameter

What it means

funcx validates user DoFn signatures via reflection. errContextParam is returned by nextParamState when a context.Context parameter appears anywhere but the first position (or more than once), since Go reflection cannot disambiguate multiple contexts and the convention requires it first.

Source

Thrown at sdks/go/pkg/beam/core/funcx/fn.go:529

	var err error
	// Validate the parameter ordering.
	for i, p := range u.Param {
		if paramState, err = nextParamState(paramState, p.Kind); err != nil {
			return errors.WithContextf(err, "validating parameter %d for %s", i, u.Fn.Name())
		}
	}
	// Validate the return value ordering.
	retState := rsStart
	for i, r := range u.Ret {
		if retState, err = nextRetState(retState, r.Kind); err != nil {
			return errors.WithContextf(err, "validating return value %d for %s", i, u.Fn.Name())
		}
	}
	return nil
}

var (
	errContextParam                      = errors.New("may only have a single context.Context parameter and it must be the first parameter")
	errPaneParamPrecedence               = errors.New("may only have a single PaneInfo parameter and it must precede the WindowParam, EventTime and main input parameter")
	errWindowParamPrecedence             = errors.New("may only have a single Window parameter and it must precede the EventTime and main input parameter")
	errEventTimeParamPrecedence          = errors.New("may only have a single beam.EventTime parameter and it must precede the main input parameter")
	errWatermarkEstimatorParamPrecedence = errors.New("may only have a single sdf.WatermarkEstimator parameter and it must precede the main input parameter")
	errReflectTypePrecedence             = errors.New("may only have a single reflect.Type parameter and it must precede the main input parameter")
	errRTrackerPrecedence                = errors.New("may only have a single sdf.RTracker parameter and it must precede the main input parameter")
	errBundleFinalizationPrecedence      = errors.New("may only have a single BundleFinalization parameter and it must precede the main input parameter")
	errStateProviderPrecedence           = errors.New("may only have a single state.Provider parameter and it must precede the main input parameter")
	errTimerProviderPrecedence           = errors.New("may only have a single timer.Provider parameter and it must precede the main input parameter")
	errInputPrecedence                   = errors.New("inputs parameters must precede emit function parameters")
)

type paramState int

const (
	psStart paramState = iota
	psContext
	psPane

View on GitHub (pinned to 12126d8942)

Solutions

Move context.Context to be the first parameter of the function.
Remove duplicate context.Context parameters, keeping only one.
If the parameter is not really a context, change its type so it isn't detected as context.Context.

Example fix

// before
func(item string, ctx context.Context) { ... }
// after
func(ctx context.Context, item string) { ... }

Defensive patterns

Strategy: validation

Validate before calling

t := reflect.TypeOf(fn)
for i, p := range paramTypes(t) {
	if p == contextType && i != 0 {
		return errors.New("context.Context must be the first parameter")
	}
}

Try / catch

if _, err := funcx.New(reflect.ValueOf(fn)); err != nil {
	return fmt.Errorf("invalid DoFn signature: %w", err)
}

Prevention

Always declare context.Context as the first parameter of Beam Go DoFns.
Have at most one context.Context per function.
Run funcx.TestNew-style signature tests in CI for custom DoFns.

When it happens

Trigger: Registering a DoFn/combineFn method like func(string, context.Context) — a context after main input — via beam.ParDo/beam.CombinePerKey/TestNew.

Common situations: Adding a context parameter later for cancellation/tracing and appending it at the end of the signature; test fn_test.go exercises exactly this case.

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