What causes "unexpected sideinput to combine: got %d, want 1" in apache/beam?

Refactor the pipeline so the Combine has a single main input; fetch side-input data before or after the combine

unexpected sideinput to combine: got %d, want 1

Error message

unexpected sideinput to combine: got %d, want 1

What it means

When translating a lifted per-key combine (urnPerKeyCombinePre), makeLink expects exactly one main input. unmarshalKeyedValues returns the non-side inputs; more (or fewer) than one means a side input was wired into the combine, which the lifted-combine translation cannot represent.

Source

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

						u = &SdfFallback{PDo: n}
					}
				}

			case graph.Combine:
				cn := &Combine{UID: b.idgen.New(), Out: out[0]}
				cn.Fn, err = graph.AsCombineFn(fn)
				if err != nil {
					return nil, err
				}
				cn.UsesKey = typex.IsKV(in[0].Type)

				cn.PID = id.to

				switch urn {
				case urnPerKeyCombinePre:
					inputs := unmarshalKeyedValues(transform.GetInputs())
					if len(inputs) != 1 {
						return nil, errors.Errorf("unexpected sideinput to combine: got %d, want 1", len(inputs))
					}
					ec, wc, err := b.makeCoderForPCollection(inputs[0])
					if err != nil {
						return nil, err
					}
					if !coder.IsKV(ec) {
						return nil, errors.Errorf("unexpected non-KV coder PCollection input to combine: %v", ec)
					}
					u = &LiftedCombine{Combine: cn, KeyCoder: ec.Components[0], WindowCoder: wc}
				case urnPerKeyCombineMerge:
					ma := &MergeAccumulators{Combine: cn}
					if pc, ok := ma.Out.(*PCollection); ok {
						if eo, ok := pc.Out.(*ExtractOutput); ok {
							// Strip PCollections from between MergeAccumulators and ExtractOutputs
							// as it's a synthetic PCollection.
							b.units = b.units[:len(b.units)-1]
							ma.Out = eo
						}

View on GitHub (pinned to 12126d8942)

Solutions

Refactor the pipeline so the Combine has a single main input; fetch side-input data before or after the combine
Inspect the submitted pipeline proto's transform Inputs and remove extra inputs
Report/fix the runner-side translation that adds inputs to urnPerKeyCombinePre transforms

Example fix

null

Defensive patterns

Strategy: validation

Validate before calling

inputs := unmarshalKeyedValues(transform.GetInputs())
if len(inputs) != 1 {
	return fmt.Errorf("combine must have exactly one main input, has %d", len(inputs))
}

Type guard

null

Try / catch

null

Prevention

Avoid attaching side inputs directly to Combine PerKey transforms
Inspect the submitted pipeline proto for unexpected inputs on combine nodes
Prefer fetching side-input data outside the combine

When it happens

Trigger: A Combine PerKey transform that also declares side inputs, or a pipeline protobuf whose Inputs map yields >1 keyed values for the pre-combine step; custom runners emitting multiple inputs on the combine transform.

Common situations: Custom/foreign runners translating via the FnAPI incorrectly; hand-modified pipeline graphs; combining with side inputs — an unsupported pattern.

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/12d69411c8c60a4a. Report an issue: GitHub.