apache/beam · error

Invalid number of components for KV: %v, %v

Error message

Invalid number of components for KV: %v, %v

What it means

FullType.New requires exactly two components for a KV composite type; anything else panics. KV is the SDK's composite of exactly key and value FullTypes, so a component count other than 2 is an invalid type construction.

Source

Thrown at sdks/go/pkg/beam/core/typex/fulltype.go:127

		return &tree{class, t, nil}
	case Container:
		switch t.Kind() {
		case reflect.Slice:
			if len(components) == 0 {
				// For elements without sub components, we just create with the type, this handles vanilla slices.
				// We include the child type as a component for convenience.
				return &tree{class, t, []FullType{New(t.Elem())}}
			}
			// For elements which themselves have components, we need to go deeper.
			return &tree{class, t, []FullType{New(t.Elem(), components[0].Components()...)}}
		default:
			panic(fmt.Sprintf("Unexpected aggregate type: %v", t))
		}
	case Composite:
		switch t {
		case KVType:
			if len(components) != 2 {
				panic(fmt.Sprintf("Invalid number of components for KV: %v, %v", t, components))
			}
			if isAnyNonKVAndNonWindowedComposite(components) {
				panic(fmt.Sprintf("Invalid to nest composite composites inside KV: %v, %v", t, components))
			}
			return &tree{class, t, components}
		case WindowedValueType:
			if len(components) != 1 {
				panic("Invalid number of components for WindowedValue")
			}
			if components[0].Type() == WindowedValueType {
				panic("Invalid to nest WindowedValue")
			}
			return &tree{class, t, components}
		case CoGBKType:
			if len(components) < 2 {
				panic(fmt.Sprintf("Invalid number of components for CoGBK: %v", t))
			}
			if isAnyNonKVComposite(components) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure exactly two components (key and value FullTypes) when constructing a KV type.
2. Build KV PCollections via beam.KV or MakeStruct helpers instead of hand-building FullType trees.
3. Validate component counts before calling typex.New with KVType.

Example fix

// before
typex.New(typex.Composite, typex.KVType, keyOnly) // 1 component: panics
// after
typex.New(typex.Composite, typex.KVType, keyFT, valueFT)

if t == typex.KVType && len(components) != 2 {
	return fmt.Errorf("KV requires exactly 2 components, got %d", len(components))
}

When it happens

Trigger: Calling typex.New with class Composite and t == typex.KVType but a components slice whose length is not 2 — e.g. from hand-assembled component lists or helpers that build KV types from unvalidated input.

Common situations: Custom code constructing KV FullTypes programmatically; schema/codegen tools emitting the wrong number of components; misuse of typex.New by passing per-element components directly.

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

• Invalid to nest composite composites inside KV: %v, %v
• invalid Class value: %v
• Unexpected aggregate type: %v
• Invalid number of components for WindowedValue
• Invalid to nest WindowedValue

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