Invalid number of components for WindowedValue

Error message

Invalid number of components for WindowedValue

What it means

FullType.New requires exactly one component for a WindowedValue composite; any other count panics. WindowedValue wraps exactly one element FullType plus window metadata handled internally, so a different component count is an invalid construction.

Source

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

			}
			// 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) {
				panic(fmt.Sprintf("Invalid to nest composites inside CoGBK: %v", t))
			}
			return &tree{class, t, components}
		case TimersType:
			return &tree{class, t, components}
		case ShardedKeyType:
			if len(components) != 1 {
				panic(fmt.Sprintf("Invalid number of components for ShardedKey: %v, %v", t, components))

View on GitHub (pinned to 12126d8942)

Solutions

Pass exactly one component (the element FullType) when constructing a WindowedValue type.
Use beam.WindowInto and the SDK's windowing APIs instead of building WindowedValue types manually.
Validate the component list length before calling typex.New.

Example fix

// before
typex.New(typex.WindowedValueType, elemFT, windowFT) // 2 components: panics
// after
typex.New(typex.WindowedValueType, elemFT)

Defensive patterns

Strategy: validation

Validate before calling

if t == typex.WindowedValueType && len(components) != 1 {
	return fmt.Errorf("WindowedValue requires exactly 1 component, got %d", len(components))
}

Prevention

Pass only the element FullType as the WindowedValue component.
Use beam.WindowInto rather than constructing WindowedValue types manually.

When it happens

Trigger: Calling typex.New with WindowedValueType and a components slice whose length is not 1 — usually from hand-assembled component lists in custom graph construction.

Common situations: Custom windowing code building WindowedValue FullTypes manually; codegen tools emitting extra components (e.g. including window/timestamp as components).

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

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