apache/beam · error

values of %v cannot bind to %v

Error message

values of %v cannot bind to %v

What it means

Apache Beam (Go) throws this while binding the value-iterator parameters of a CoGBK side input: each parameter after the key must be an FnIter (or FnReIter) whose element unfolds to exactly 1 legal component after trimIllegal. If the iterator's element type is itself a composite whose components get trimmed to 0 or 2+ entries, the iterator cannot represent a single CoGBK value stream and binding fails.

Source

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

				default:
					return nil, kind, errors.Errorf("%v cannot bind to %v", t, args[0])
				}
			}

		case typex.CoGBKType:
			if args[0].Kind != funcx.FnValue {
				return nil, kind, errors.Errorf("key of %v cannot bind to %v", t, args[0])
			}

			components := []typex.FullType{typex.New(args[0].T)}

			for i := 1; i < len(args); i++ {
				switch args[i].Kind {
				case funcx.FnIter:
					values, _ := funcx.UnfoldIter(args[i].T)
					trimmed := trimIllegal(values)
					if len(trimmed) != 1 {
						return nil, kind, errors.Errorf("values of %v cannot bind to %v", t, args[i])
					}
					components = append(components, typex.New(trimmed[0]))

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

		default:
			return nil, kind, errors.Errorf("unexpected inbound type: %v", t.Type())

View on GitHub (pinned to 12126d8942)

Solutions

1. Make each value parameter iterate exactly the plain value type, not a KV: func(k K, v1 func(*func.Iter) bool, v2 func(*func.Iter) bool) bool
2. Extract values from nested KVs (beam.ExtractKV / restructure the pipeline) so the iterator yields a single concrete component
3. Use a MultiMap parameter only for the CoGBK-as-map access pattern, not mixed with per-input Iter parameters
4. Check that CoGBK inputs are PCollections of plain values, not KVs, unless you intend the KV as the value component

Example fix

// before
func(k string, kv func(*func.Iter) bool) bool { /* iterates KV<K2,V2> */ }
// after
func(k string, v func(*func.Iter) bool) bool { /* iterates plain V */ }

// Each CoGBK value parameter must iterate a single concrete component
// el := reflect.TypeOf(iterElem) ; require typex.ClassOf(el) in {Concrete, Universal, Container}

func iterElemIsSingleComponent(fn interface{}, idx int) bool {
	t := reflect.TypeOf(fn)
	if t == nil || idx >= t.NumIn() {
		return false
	}
	p := t.In(idx)
	return p.Kind() == reflect.Func && p.NumIn() == 1 && p.In(0).Kind() == reflect.Ptr
}

When it happens

Trigger: A CoGBK side-input function whose value parameter is func(i *func.Iter) bool where the iterated element is a KV or other multi-component composite (UnfoldIter + trimIllegal yields len != 1); also fires when the parameter kind is FnMultiMap or another unsupported kind (default branch, same message).

Common situations: Iterating KV pairs in a CoGBK value parameter (should iterate plain values; the key is already a separate parameter); passing a MultiMap parameter where per-input Iter parameters are expected; nesting KVs inside CoGBK values so trimIllegal strips/miscounts components.

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

• side input in method %v does not match side input in %v
• combine does not support side inputs
• side input closed
• invalid side pcollection: index %v
• GroupIntoBatches: input PCollection must be KV-typed; got %v

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