What causes "%v cannot bind to %v" in apache/beam?

Change the parameter to match the input shape, e.g. accept KV via func(K, func(V) bool) or a KV-typed value.

%v cannot bind to %v

Error message

%v cannot bind to %v

What it means

tryBindInbound matches a requested parameter kind (here an Iter function) against the actual inbound type available from the input PCollection. When an Iter<T> parameter is used but unpacking the input type does not yield exactly one element type, the bind fails with '%v cannot bind to %v', indicating the function parameter type cannot consume the input the pipeline provides.

Source

Thrown at sdks/go/pkg/beam/core/graph/bind.go:201

			// string by matching up the incoming type and the param type.

			arg := args[0]
			switch arg.Kind {
			case funcx.FnValue:
				if args[0].T.Kind() == reflect.Slice && t.Type() == args[0].T.Elem() {
					// TODO(herohde) 6/29/2017: we do not allow universal slices, for now.

					kind = Slice
					other = typex.New(args[0].T.Elem())
				} else {
					kind = Singleton
					other = typex.New(args[0].T)
				}
			case funcx.FnIter:
				values, _ := funcx.UnfoldIter(args[0].T)
				trimmed := trimIllegal(values)
				if len(trimmed) != 1 {
					return nil, kind, errors.Errorf("%v cannot bind to %v", t, args[0])
				}

				kind = Iter
				other = typex.New(trimmed[0])

			case funcx.FnReIter:
				values, _ := funcx.UnfoldReIter(args[0].T)
				trimmed := trimIllegal(values)
				if len(trimmed) != 1 {
					return nil, kind, errors.Errorf("%v cannot bind to %v", t, args[0])
				}

				kind = ReIter
				other = typex.New(trimmed[0])

			case funcx.FnMultiMap:
				return nil, kind, errors.Errorf("input to MultiMap side input must be KV, got %v", t)

View on GitHub (pinned to 12126d8942)

Solutions

Change the parameter to match the input shape, e.g. accept KV via func(K, func(V) bool) or a KV-typed value.
Restructure the pipeline so the input to this DoFn is a plain single-element PCollection.
Print the input PCollection's type (pcoll.Type()) and align the DoFn's inbound parameter with it.

Example fix

// before
func (f *fn) ProcessElement(it func(int) bool) { ... } // input is KV<string,int>
// after
func (f *fn) ProcessElement(k string, v int) { ... }

Defensive patterns

Strategy: validation

Validate before calling

values, _ := funcx.UnfoldIter(inputType)
if len(funcx.TrimIllegal(values)) != 1 {
    return fmt.Errorf("input %v cannot feed an Iter parameter", inputType)
}

Prevention

Inspect pcoll.ElementType() before writing the DoFn signature.
Match KV inputs with KV-style parameters, not plain iterators.
Re-check DoFn signatures whenever upstream transforms change output shapes.

When it happens

Trigger: Using a func(func(T) bool) (iterator) parameter while the input PCollection is empty, a KV, or a coder whose UnfoldIter does not produce exactly one element type; feeding a KV stream into a function expecting a plain iter.

Common situations: ParDo on a KV output where the DoFn declares a single-value iterator; mismatched side-input types; pipeline shape changed upstream (e.g. a beam.ParDo after beam.KV-producing transform) without updating the DoFn signature.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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