side input in method %v does not match side input in %v

Error message

side input in method %v does not match side input in %v

What it means

After counts match, validateSideInputs compares each side input's type: the i-th side input parameter of the auxiliary method must have the same type as the i-th side input of ProcessElement (skipping main inputs). A funcx.TypeMismatchError wrapped with this message is returned from AsDoFn on mismatch.

Source

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

	}

	// Error if number of side inputs doesn't match.
	if numMethodIn != numSideIn {
		err := errors.Errorf("number of side inputs in method %v does not match method %v: got %d, expected %d",
			methodName, processElementName, numMethodIn, numSideIn)
		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]
	sideInputs := processFnInputs[numMainIn:] // Skip main inputs in ProcessFn
	for i := 0; i < len(sideInputs); 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,
				"Incorrect side inputs in the %v method of a DoFn. "+
					"The side inputs should match those of the %v method.",
				methodName, processElementName)
		}
	}

	return nil
}

// validateSideInputsNumUnknown does similar validation as validateSideInputs, but for an unknown
// number of main inputs.
func validateSideInputsNumUnknown(processFnInputs []funcx.FnParam, method *funcx.Fn, methodName string) error {
	// Note: By the time this is called, we should have already know that ProcessElement has at
	// 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.

View on GitHub (pinned to 12126d8942)

Solutions

Make each auxiliary method side input type exactly equal to the corresponding ProcessElement side input type.
Check whether the side input PCollection should be KV (use beam.KV and a KV side input) or single value (beam.V).
Update the pipeline's beam.Input/side input construction if the element type changed intentionally.

Example fix

// before
func (fn *myFn) ProcessElement(w string, side beam.V) {}
func (fn *myFn) FinishBundle(side beam.KV) {}

// after
func (fn *myFn) ProcessElement(w string, side beam.V) {}
func (fn *myFn) FinishBundle(side beam.V) {}

Defensive patterns

Strategy: validation

Validate before calling

// check side input PCollection type before wiring:
// KV side input -> beam.KV params; single-value side input -> beam.V params

Type guard

func isKvSideInput(t reflect.Type) bool { return strings.Contains(t.String(), "KV") }

Try / catch

if err := buildPipeline(); err != nil {
	var tm *funcx.TypeMismatchError
	if errors.As(err, &tm) { log.Fatalf("side input type: got %v want %v", tm.Got, tm.Want) }
}

Prevention

Copy side input parameter declarations verbatim from ProcessElement
Decide V vs KV per side input once and use it in every method
Update all methods when a side input PCollection's element type changes

When it happens

Trigger: Declaring ProcessElement side input as beam.V (single value) but auxiliary method side input as beam.KV, or different element types (e.g. Iter[string] vs string), then converting the DoFn with AsDoFn.

Common situations: Side input built with beam.Input yielding KV vs single values; switching a side input's underlying PCollection type without updating methods; using beam.V/beam.KV constants inconsistently across methods.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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