may only have a single PaneInfo parameter and it must preced

Error message

may only have a single PaneInfo parameter and it must precede the WindowParam, EventTime and main input parameter

What it means

funcx enforces parameter ordering for special DoFn parameters: typex.PaneInfo must appear before typex.Window, typex.EventTime and the main input, and only one PaneInfo is allowed. nextParamState returns errPaneParamPrecedence when a FnPane parameter is seen out of order.

Source

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

	// 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
	psWindow

View on GitHub (pinned to 12126d8942)

Solutions

Reorder so PaneInfo comes before Window, EventTime, and the main input parameter.
Remove any duplicate PaneInfo parameter.
Update the signature per funcx docs: context, pane, window, event-time, then main input.

Example fix

// before
func(w typex.Window, p typex.PaneInfo, v int) { ... }
// after
func(p typex.PaneInfo, w typex.Window, v int) { ... }

Defensive patterns

Strategy: validation

Validate before calling

// ensure PaneInfo precedes Window/EventTime/main input
for i, p := range paramTypes(fn) {
	if p == paneInfoType && i > paneAllowedIndex(paramTypes(fn)) {
		return errors.New("PaneInfo must precede Window, EventTime and main input")
	}
}

Try / catch

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

Prevention

Use canonical parameter order: context, PaneInfo, Window, EventTime, main input.
Only one PaneInfo parameter per function.
Cover each DoFn signature with a funcx.New unit test.

When it happens

Trigger: Signatures such as func(typex.Window, typex.PaneInfo, int) where PaneInfo follows a Window (or main input) parameter, or functions with two PaneInfo params.

Common situations: Reordering parameters while editing DoFns for windowing/pane handling and accidentally placing PaneInfo after Window.

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