apache/beam · error

could not unmarshal nullable coder from

Error message

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

What it means

Error returned by makeCoder when a nullable coder URN arrives with a component count other than one. Nullable wraps exactly one inner element coder; any other arity indicates a malformed CoderRef in the pipeline proto or a version skew between producer and consumer of the pipeline.

Solutions

1. Ensure the nullable coder nests exactly one element coder component
2. Regenerate the pipeline with a current Go SDK
3. Fix hand-written CoderRef JSON to include one component
4. Check SDK version skew if a foreign producer wrote the coder

Example fix

// before: nullable coder with 0 components
// after: {"urn":"beam:coder:nullable:v1","components":[{"urn":"beam:coder:string_utf8:v1","components":[]}]}

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

When it happens

Trigger: Decoding a nullable coder whose components list is empty or has more than one entry.

Common situations: Hand-edited pipeline JSON; graphs generated by SDK versions before nullable coder support; corrupted job 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 iterable 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/6fb3066b4ee7220e. Report an issue: GitHub.

Appendix: source

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

		}
		w, err := b.WindowCoder(components[1])
		if err != nil {
			return nil, errors.Errorf("could not unmarshal window coder for timer: %w", err)
		}
		return coder.NewT(elm, w), nil
	case urnRowCoder:
		var s pipepb.Schema
		if err := proto.Unmarshal(c.GetSpec().GetPayload(), &s); err != nil {
			return nil, err
		}
		t, err := schema.ToType(&s)
		if err != nil {
			return nil, err
		}
		return coder.NewR(typex.New(t)), nil
	case urnNullableCoder:
		if len(components) != 1 {
			return nil, errors.Errorf("could not unmarshal nullable 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.NewN(elm), nil
	case urnShardedKeyCoder:
		if len(components) != 1 {
			return nil, errors.Errorf("could not unmarshal sharded_key coder from %v, expected one component (key) but got %d", c, len(components))
		}
		keyC, err := b.Coder(components[0])
		if err != nil {
			return nil, err
		}
		return coder.NewSK(keyC), nil
	case urnIntervalWindow:
		return coder.NewIntervalWindowCoder(), nil

View on GitHub (pinned to 12126d8942)