apache/beam · error

invalid SideInput payload for %v

Error message

invalid SideInput payload for %v

What it means

A URNMapWindows transform's payload should unmarshal into a pipepb.FunctionSpec describing the window-mapping function (e.g. side-input views). If proto.Unmarshal fails, the payload is not a valid FunctionSpec and makeLink returns this error (message says 'SideInput payload' because MapWindows handles side-input window mapping).

Source

Thrown at sdks/go/pkg/beam/core/runtime/exec/translate.go:797

		default:
			return nil, errors.Errorf("unexpected payload: %v", &tp)
		}

	case graphx.URNWindow:
		var wp pipepb.WindowIntoPayload
		if err := proto.Unmarshal(payload, &wp); err != nil {
			return nil, errors.Wrapf(err, "invalid WindowInto payload for %v", transform)
		}
		wfn, err := unmarshalWindowFn(wp.GetWindowFn())
		if err != nil {
			return nil, err
		}
		u = &WindowInto{UID: b.idgen.New(), Fn: wfn, Out: out[0]}

	case graphx.URNMapWindows:
		var fn pipepb.FunctionSpec
		if err := proto.Unmarshal(payload, &fn); err != nil {
			return nil, errors.Wrapf(err, "invalid SideInput payload for %v", transform)
		}
		mapper, err := unmarshalAndMakeWindowMapping(&fn)
		if err != nil {
			return nil, err
		}
		u = &MapWindows{UID: b.idgen.New(), Fn: mapper, Out: out[0], FnUrn: fn.GetUrn()}

	case graphx.URNFlatten:
		u = &Flatten{UID: b.idgen.New(), N: len(transform.Inputs), Out: out[0]}

		// Use the same flatten instance for all the inputs links to this transform.
		for i := 0; i < len(transform.Inputs); i++ {
			b.links[linkID{id.to, i}] = u
		}

	case urnDataSink:
		port, cid, err := unmarshalPort(payload)
		if err != nil {

View on GitHub (pinned to 12126d8942)

Solutions

1. Regenerate and resubmit the pipeline with a stock Beam SDK so the payload is a valid FunctionSpec
2. Check the payload offline: proto.Unmarshal(payload, &pipepb.FunctionSpec{}) should succeed
3. Align SDK/runner versions to eliminate schema drift

Example fix

null

var fn pipepb.FunctionSpec
if err := proto.Unmarshal(payload, &fn); err != nil {
	return fmt.Errorf("payload is not a FunctionSpec: %w", err)
}

null

if _, err := graph.MakePipeline(pipelineProto); err != nil {
	if strings.Contains(err.Error(), "invalid SideInput payload") {
		// regenerate the pipeline; check for foreign-runner payload schema issues
	}
}

When it happens

Trigger: MapWindows payload bytes that are not a FunctionSpec protobuf — corrupt job submission, a foreign runner emitting a different payload schema for MapWindows, or bytes shifted by a transport/serialization bug.

Common situations: Custom/foreign runners; hand-edited pipeline graphs; cross-version SDK skew altering payload encoding for side-input window mappings.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

• invalid WindowInto payload for %v
• session windowing is not supported for side inputs
• Unable to create a side-input view from input
• Attempted to get side input window for GlobalWindow from non
• Sessions is not allowed in side inputs

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