number of side inputs in method %v does not match method %v:

Error message

number of side inputs in method %v does not match method %v: got %d, expected either %d or %d

What it means

For DoFn methods where the main input cardinality is unknown (single vs KV), validateSideInputsNumUnknown accepts only two possible side input counts: numProcessIn - 1 (main is single) or numProcessIn - 2 (main is KV). This error is thrown from AsDoFn when the auxiliary method's input count matches neither, meaning the number of side inputs is inconsistent with ProcessElement under either interpretation.

Source

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

	// least two inputs, and the second input is ambiguous (could be either a main input or side
	// input). Since we don't know how to interpret the second input, these checks will be more
	// permissive than they would be otherwise.
	posMethodIn, numMethodIn, ok := method.Inputs()
	numProcessIn := len(processFnInputs)

	// Handle cases where method has no inputs.
	if !ok {
		// If there's no inputs, this is fine, as the ProcessElement method could be a
		// CoGBK, and not have side inputs.
		return nil
	}

	// Error if number of side inputs doesn't match any of the possible numbers of side inputs,
	// defined below.
	numSideInSingle := numProcessIn - int(MainSingle)
	numSideInKv := numProcessIn - int(MainKv)
	if numMethodIn != numSideInSingle && numMethodIn != numSideInKv {
		err := errors.Errorf("number of side inputs in method %v does not match method %v: got %d, expected either %d or %d",
			methodName, processElementName, numMethodIn, numSideInSingle, numSideInKv)
		return errors.SetTopLevelMsgf(err,
			"Incorrect number of side inputs in the %v method of a DoFn. "+
				"The side inputs should match those of the %v method.",
			methodName, processElementName)
	}

	// Error if there's a type mismatch.
	methodInputs := method.Param[posMethodIn : posMethodIn+numMethodIn]
	// If there's N inputs in the method, then we compare with the last N inputs to processElement.
	offset := numProcessIn - numMethodIn
	sideInputs := processFnInputs[offset:]
	for i := 0; i < numMethodIn; i++ {
		if sideInputs[i].T != methodInputs[i].T {
			var err error = &funcx.TypeMismatchError{Got: methodInputs[i].T, Want: sideInputs[i].T}
			err = errors.Wrapf(err, "side input in method %v does not match side input in %v",
				methodName, processElementName)
			return errors.SetTopLevelMsgf(err,

View on GitHub (pinned to 12126d8942)

Solutions

Adjust the auxiliary method's input count so inputs minus 1 (single-element form) or minus 2 (KV form) equals ProcessElement's side input count.
Remove or add side input parameters to match one of the two accepted shapes.
Mirror ProcessElement's parameter list exactly, changing only the main input form.

Example fix

// before (ProcessElement has 1 main + 2 side inputs = 3 params)
func (fn *myFn) FinishBundle(a beam.V, b beam.V) {} // only 2 inputs

// after
func (fn *myFn) FinishBundle(w string, a beam.V, b beam.V) {} // 1 main + 2 side inputs

Defensive patterns

Strategy: validation

Validate before calling

// accepted shapes for auxiliary method inputs: len(PE params) - 1 or len(PE params) - 2
n := numProcessElementInputs
ok := auxInputs == n-1 || auxInputs == n-2

Type guard

func auxInputCountValid(aux, pe int) bool { return aux == pe-1 || aux == pe-2 }

Try / catch

if err := beam.ParDo(s, fn, in); err != nil { log.Fatalf("side input count: %v", err) }

Prevention

Mirror ProcessElement's parameter list in auxiliary methods, changing only the main input form
Do not add extra parameters (ctx, timestamps) ad hoc to auxiliary methods
Test signature registration early with a tiny pipeline

When it happens

Trigger: A StartBundle/FinishBundle/Setup/Teardown method declaring a number of inputs such that, after subtracting either 1 (MainSingle) or 2 (MainKv) main inputs, the remainder never equals ProcessElement's side input count; e.g. an extra context or unexpected parameter shifting the count.

Common situations: Auxiliary method includes extra parameters (context, event time, etc.) not present in the expected shape; mixing a KV-form ProcessElement with a wrongly sized auxiliary method; hand-writing signatures instead of mirroring ProcessElement.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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