may only have a single beam.EventTime parameter and it must

Error message

may only have a single beam.EventTime parameter and it must precede the main input parameter

What it means

funcx requires a single beam.EventTime (typex.EventTime) parameter and that it precede the main input. nextParamState returns errEventTimeParamPrecedence when an EventTime parameter appears after the main input or more than once.

Source

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

		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
	psWindow
	psEventTime
	psWatermarkEstimator

View on GitHub (pinned to 12126d8942)

Solutions

Move typex.EventTime so it precedes the main input parameter.
Remove duplicate EventTime parameters.
Verify only special (non-input) parameters precede the main input, in documented order.

Example fix

// before
func(v int, et typex.EventTime) { ... }
// after
func(et typex.EventTime, v int) { ... }

Defensive patterns

Strategy: validation

Validate before calling

for i, p := range paramTypes(fn) {
	if p == eventTimeType && i >= mainInputIndex(paramTypes(fn)) {
		return errors.New("EventTime must precede the main input")
	}
}

Try / catch

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

Prevention

Insert typex.EventTime before the main input parameter, not after.
Only one EventTime parameter per function.
Test each DoFn signature with funcx.New during development.

When it happens

Trigger: Signatures like func(int, typex.EventTime) — EventTime after the main input — or two EventTime params, registered through beam.ParDo/TestNew.

Common situations: Adding event-timestamp access to an existing DoFn by appending the parameter instead of inserting it before the main input.

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