apache/beam · error

could not unmarshal iterable coder from

Error message

could not unmarshal iterable coder from %v, expected one component but got %d

What it means

Iterable coders (beam:coder:iterable:v1 and the state-backed variant) must have exactly one component coder describing the element type. makeCoder found a different component count, so it cannot build coder.NewI.

Solutions

1. Inspect the coder's components list and ensure exactly one element coder is nested
2. Regenerate the pipeline graph with the Go SDK
3. Fix hand-written CoderRef JSON to nest one component under the iterable coder
4. Align SDK versions if a foreign runner produced the coder

Example fix

// before: iterable coder with no components
// after: {"urn":"beam:coder:iterable:v1","components":[{"urn":"beam:coder:varint:v1","components":[]}]}

if ref.Urn == "beam:coder:iterable:v1" && len(ref.Components) != 1 {
    return fmt.Errorf("iterable coder must have exactly 1 component, got %d", len(ref.Components))
}

When it happens

Trigger: Decoding an iterable coder whose components list has 0 or 2+ entries — typically a malformed or foreign-encoded pipeline graph.

Common situations: Hand-edited pipeline JSON; graphs produced by other SDKs with different arity conventions; corrupted job submission artifacts.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• could not unmarshal nullable coder from
• could not unmarshal sharded_key coder from
• array len mismatch. decoding
• capacity of cache cannot be negative, got
• coder must not be nil

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/graphx/coder.go:344

	case "":
		// TODO(herohde) 11/27/2017: we still see CoderRefs from Dataflow. Handle that
		// case here, for now, so that the harness can use this logic.

		payload := c.GetSpec().GetPayload()

		var ref CoderRef
		if err := json.Unmarshal(payload, &ref); err != nil {
			return nil, errors.Wrapf(err, "could not unmarshal CoderRef from %v, failed to decode urn-less coder's payload \"%v\"", c, string(payload))
		}
		c, err := DecodeCoderRef(&ref)
		if err != nil {
			return nil, errors.Wrapf(err, "could not unmarshal CoderRef from %v, failed to decode CoderRef \"%v\"", c, string(payload))
		}
		return c, nil

	case urnIterableCoder, urnStateBackedIterableCoder:
		if len(components) != 1 {
			return nil, errors.Errorf("could not unmarshal iterable coder from %v, expected one component but got %d", c, len(components))
		}
		elm, err := b.Coder(components[0])
		if err != nil {
			return nil, err
		}
		return coder.NewI(elm), nil
	case urnTimerCoder:
		if len(components) != 2 {
			return nil, errors.Errorf("could not unmarshal timer coder from %v, expected two component but got %d", c, len(components))
		}
		elm, err := b.Coder(components[0])
		if err != nil {
			return nil, err
		}
		w, err := b.WindowCoder(components[1])
		if err != nil {
			return nil, errors.Errorf("could not unmarshal window coder for timer: %w", err)
		}

View on GitHub (pinned to 12126d8942)