Invalid to nest composite composites inside KV: %v, %v

Error message

Invalid to nest composite composites inside KV: %v, %v

What it means

FullType.New rejects KV composites whose components include composite types that are neither KV nor WindowedValue. Nesting arbitrary composites inside a KV would break the SDK's encoding and grouping assumptions, so it panics instead.

Source

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

		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) {
				panic(fmt.Sprintf("Invalid to nest composites inside CoGBK: %v", t))
			}
			return &tree{class, t, components}

View on GitHub (pinned to 12126d8942)

Solutions

Flatten nested composites: use KV of concrete or container types only.
If grouping multiple values, use CoGBK (KV<K, Iter<V>>) shapes rather than nesting composites.
Wrap the value in WindowedValue if windowing metadata must be nested.

Example fix

// before
typex.New(typex.KVType, coGBKComponent, valueFT) // nested composite: panics
// after
typex.New(typex.KVType, keyFT, valueFT)

Defensive patterns

Strategy: validation

Validate before calling

for _, c := range components {
	if c.Type() == typex.Composite && c.Type() != typex.KVType && c.Type() != typex.WindowedValueType {
		return errors.New("cannot nest composites inside KV")
	}
}

Prevention

Keep KV values as concrete, container, KV, or WindowedValue types only.
Model multi-collection grouping with CoGBK rather than nested composites.

When it happens

Trigger: Calling typex.New with KVType where at least one of the two components is itself a composite class (e.g. CoGBK or nested composite) rather than a concrete/Container/KV/WindowedValue type.

Common situations: Building deeply nested custom composite types for pipeline data; migrating pipelines that used nested composite representations unsupported by the Go SDK.

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

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