apache/beam · error

GBK/CoGBK result values must be iterable: %v

Error message

GBK/CoGBK result values must be iterable: %v

What it means

When a DoFn receives GBK/CoGBK results, each value parameter must be an iterator function (func(*T) bool) matching funcx.FnIter. If the declared parameter kind is not an iterator, invokeWithOpts returns this error with the offending param. The Go DoFn signature does not match the shape required to consume the grouped values.

Source

Thrown at sdks/go/pkg/beam/core/runtime/exec/fn.go:275

			from := reflect.TypeOf(opts.opt.Key.Elm)
			n.elmConvert = ConvertFn(from, fn.Param[in[i]].T)
		}
		args[in[i]] = n.elmConvert(opts.opt.Key.Elm)
		i++
		if opts.opt.Key.Elm2 != nil {
			if n.elm2Convert == nil {
				from := reflect.TypeOf(opts.opt.Key.Elm2)
				n.elm2Convert = ConvertFn(from, fn.Param[in[i]].T)
			}
			args[in[i]] = n.elm2Convert(opts.opt.Key.Elm2)
			i++
		}

		for _, iter := range opts.opt.Values {
			param := fn.Param[in[i]]

			if param.Kind != funcx.FnIter {
				return nil, errors.Errorf("GBK/CoGBK result values must be iterable: %v", param)
			}

			// TODO(herohde) 12/12/2017: allow form conversion on GBK results?

			it := makeIter(param.T, iter)
			it.Init()
			args[in[i]] = it.Value()
			// Ensure main value iterators are reset & closed after the invoke to avoid
			// short read problems.
			defer it.Reset()
			i++
		}
	}

	// (3) Precomputed side input and emitters (or other output).
	for _, arg := range opts.extra {
		args[in[i]] = arg
		i++

View on GitHub (pinned to 12126d8942)

Solutions

1. Change the values parameter to an iterator function signature: func(vs func(*V) bool) or func(k string, vs func(*V) bool)
2. Check beam.reflect.MakeFunc4/invoke docs for accepted ProcessElement signatures
3. Use beam.TryGrouped/CoGBK examples from the SDK as reference
4. Recompile and inspect fn.Param diagnostics for the DoFn

Example fix

// before
func (fn *myFn) ProcessElement(k string, vs []V) {
    for _, v := range vs { ... } // not iterable param kind
}
// after
func (fn *myFn) ProcessElement(k string, vs func(*V) bool) {
    var v V
    for vs(&v) { ... }
}

// check DoFn param shape before registering
// values param for GBK must be func(*V) bool
func isIterParam(fn interface{}) bool {
    t := reflect.TypeOf(fn)
    return t.Kind() == reflect.Func && t.NumIn() == 1 &&
        t.In(0).Kind() == reflect.Ptr && t.Out(0).Kind() == reflect.Bool
}

// DoFn signature errors are caught at plan-build/invoke time
if err != nil && strings.Contains(err.Error(), "must be iterable") {
    return fmt.Errorf("fix ProcessElement signature: values param must be func(*V) bool: %w", err)
}

When it happens

Trigger: A ProcessElement handling GBK output declares the values parameter as a slice, concrete type, or function that is not `func(*V) bool`; opts.opt.Values contains iterables but param.Kind != funcx.FnIter.

Common situations: Migrating from Python/Java Beam where GBK results arrive as lists; writing ProcessElement(k string, vs []V) instead of an iterator function; misuse of beam.CoGBK outputs in Go.

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

• bad parameter type for %s: %v
• Invalid signature for FinishBundle
• first main input parameter must be a value type
• ProcessElement uses a TimerProvider, but no Timer fields are
• ExecuteTransform[GBK] stage %v, transform %q %v: couldn't pr

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