apache/beam · error

ShardedKey coder requires exactly 1 component (key), got

Error message

ShardedKey coder requires exactly 1 component (key), got %d

What it means

A coder.ShardedKey was declared with a component count other than exactly 1 during marshalling. ShardedKey coders by definition carry only the key component, so 0 or 2+ components is a structural invariant violation.

Solutions

1. Fix the coder construction so ShardedKey has exactly one component: coder.NewShardedKey(keyType)
2. Check code that builds coders programmatically for wrong arity
3. Verify the expansion/transform producing this coder emits a single-component ShardedKey
4. Upgrade the SDK if a transform generates the malformed coder

Example fix

// before
c := &coder.Coder{Kind: coder.ShardedKey, Components: []*coder.Coder{key, value}}
// after
c := &coder.Coder{Kind: coder.ShardedKey, Components: []*coder.Coder{key}}

// Guard coder construction before calling Add
func validShardedKey(c *coder.Coder) bool {
    return c.Kind != coder.ShardedKey || len(c.Components) == 1
}

func isShardedKey(c *coder.Coder) bool { return c != nil && c.Kind == coder.ShardedKey && len(c.Components) == 1 }

When it happens

Trigger: Constructing a coder.ShardedKey with an empty or multi-element Components slice and passing it to CoderBuilder.Add; programmatic coder construction with wrong arity.

Common situations: Custom pipeline-construction code or cross-language expansion producing ShardedKey coders with wrong component counts; manual coder assembly bugs.

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 coder kind
• bad decoding function
• bad encoding function
• bad window kind
• could not unmarshal coder from

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

Appendix: source

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

		value := comp[1]
		if len(comp) > 2 {
			// TODO(https://github.com/apache/beam/issues/18032): don't inject union coder for CoGBK.

			union := b.internBuiltInCoder(urnCoGBKList, comp[1:]...)
			value = b.internBuiltInCoder(urnLengthPrefixCoder, union)
		}

		// SDKs always provide iterableCoder to runners, but can receive StateBackedIterables in return.
		stream := b.internBuiltInCoder(urnIterableCoder, value)
		return b.internBuiltInCoder(urnKVCoder, comp[0], stream), nil

	case coder.ShardedKey:
		comp, err := b.AddMulti(c.Components)
		if err != nil {
			return "", errors.Wrapf(err, "failed to marshal ShardedKey coder %v", c)
		}
		if len(comp) != 1 {
			return "", errors.Errorf("ShardedKey coder requires exactly 1 component (key), got %d", len(comp))
		}
		return b.internBuiltInCoder(urnShardedKeyCoder, comp...), nil

	case coder.WindowedValue:
		comp := []string{}
		if ids, err := b.AddMulti(c.Components); err != nil {
			return "", errors.Wrapf(err, "failed to marshal window coder %v", c)
		} else {
			comp = append(comp, ids...)
		}
		if id, err := b.AddWindowCoder(c.Window); err != nil {
			return "", errors.Wrapf(err, "failed to marshal window coder %v", c)
		} else {
			comp = append(comp, id)
		}
		return b.internBuiltInCoder(urnWindowedValueCoder, comp...), nil

	case coder.Bytes:

View on GitHub (pinned to 12126d8942)