apache/beam · critical

ShardedKey coder must have only 1 component: %s

Error message

ShardedKey coder must have only 1 component: %s

What it means

A ShardedKey coder must contain exactly one component coder (the key element coder). prism panics when the component list length differs, meaning the SDK sent a structurally invalid sharded-key coder.

Source

Thrown at sdks/go/pkg/beam/runners/prism/internal/coders.go:373

		return func(r io.Reader) {
			kd(r)
			vd(r)
		}
	case urns.CoderWindowedValue:
		ccids := c.GetComponentCoderIds()
		if len(ccids) != 2 {
			panic(fmt.Sprintf("WindowedValue coder with more than 2 components: %s", prototext.Format(c)))
		}
		ed := pullDecoderNoAlloc(coders[ccids[0]], coders)
		wd := pullDecoderNoAlloc(coders[ccids[1]], coders)
		return func(r io.Reader) {
			ed(r)
			wd(r)
		}
	case urns.CoderShardedKey:
		ccids := c.GetComponentCoderIds()
		if len(ccids) != 1 {
			panic(fmt.Sprintf("ShardedKey coder must have only 1 component: %s", prototext.Format(c)))
		}
		kd := pullDecoderNoAlloc(coders[ccids[0]], coders)
		return func(r io.Reader) {
			l, _ := coder.DecodeVarInt(r)
			ioutilx.ReadN(r, int(l))
			kd(r)
		}
	case urns.CoderRow:
		panic(fmt.Sprintf("Runner forgot to LP this Row Coder. %v", prototext.Format(c)))
	default:
		panic(fmt.Sprintf("unknown coder urn key: %v", urn))
	}
}

// debugCoder is developer code to get the structure of a proto coder visible when
// debugging coder errors in prism. It may sometimes be unused, so we do this to avoid
// linting errors.
var _ = debugCoder

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the printed coder proto: component_coder_ids must have exactly 1 entry
2. Remove or fix custom coder overrides affecting sharded keys
3. Use stock Beam coder construction for sharded keys on the SDK side
4. Test with a minimal GroupByKey pipeline to isolate the source

if len(skCoder.GetComponentCoderIds()) != 1 { return fmt.Errorf("ShardedKey coder must have exactly 1 component, got %d", len(skCoder.GetComponentCoderIds())) }

defer func() { if r := recover(); r != nil { log.Errorf("sharded-key coder panicked: %v", r) } }()

When it happens

Trigger: pullDecoderNoAlloc handles urn beam:coders:sharded_key:v1 whose GetComponentCoderIds() length != 1 — e.g. components list empty or containing multiple coder IDs.

Common situations: Custom GroupByKey/sharded-key coder customization gone wrong; hand-assembled coder protos in tests or tools; SDK/runner version skew changing sharded-key representation.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• KV coder with more than 2 components: %s
• WindowedValue coder with more than 2 components: %s
• Runner forgot to LP this Row Coder. %v
• unknown coder urn key: %v
• %v

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