What causes "Invalid to nest composites inside CoGBK: %v" in apache/beam?

Flatten or restructure the composite components so each CoGBK component is a plain KV type (KV ).

Invalid to nest composites inside CoGBK

Error message

Invalid to nest composites inside CoGBK: %v

What it means

typex.New constructs the full-type tree and validates CoGBK types. A CoGBK type must have at least 2 components and every component must be a simple KV (or key-like) type; if isAnyNonKVComposite finds a non-KV composite among the components, New panics with this message. The Beam Go SDK intentionally forbids arbitrarily nested composite types inside CoGBK because its translation layer (CoGBK to GBK or union encodings) cannot represent them.

Solutions

Flatten or restructure the composite components so each CoGBK component is a plain KV type (KV<K,V>).
If you truly need nesting, encode the nested value yourself, e.g. wrap it in a KV whose value is an encoded []byte, the pattern the SDK itself uses for CoGBK translation.
Check which helper (CoGroupByKey, CombinePerKey, etc.) supplied the offending type and pass a simpler typex.FullType instead.

Example fix

// before
typex.New(typex.CoGBKType, kvType, windowedType)
// after
typex.New(typex.CoGBKType, kvType, typex.NewKV(keyType, valueType))

Defensive patterns

Strategy: validation

Validate before calling

func validCoGBKComponents(cs []typex.FullType) bool {
    if len(cs) < 2 { return false }
    for _, c := range cs {
        if c == nil || (c.Class() == typex.Composite && c.Type() != typex.KVType) { return false }
    }
    return true
}

Try / catch

func safeNew(t typex.Type, cs ...typex.FullType) (ft typex.FullType, err error) {
    defer func() {
        if r := recover(); r != nil { err = fmt.Errorf("typex.New: %v", r) }
    }()
    return typex.New(t, cs...), nil
}

Prevention

Only pass plain KV components to CoGBK types.
Wrap nested values in encoded []byte form, as the SDK's own translation does.
Prefer beam's transform helpers (CoGroupByKey, CombinePerKey) over manual typex.New calls.

When it happens

Trigger: Calling typex.New with a Composite type of class CoGBKType whose components include any non-KV composite, e.g. CoGBK<T1,WindowedValue<T2>> or CoGBK<KV<A,B>,T>. Reached via the public New constructor, which is invoked by beam type helpers such as CoGroupByKey, CombinePerKey, CombineGlobally, Flatten, GroupByKey and Prefix.

Common situations: Building custom PCollection coders/types for cross-bucket joins where a windowed or composite value type is passed as a CoGBK component; mixing typex.New(T, components...) manually with types that were legal in older Beam versions where nesting rules were looser.

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/19c0bdb933772826. Report an issue: GitHub.

Appendix: source

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

			}
			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))
			}
			if components[0].Class() == Composite {
				panic(fmt.Sprintf("Invalid to nest composite inside ShardedKey: %v, %v", t, components))
			}
			return &tree{class, t, components}
		default:
			panic(fmt.Sprintf("Unexpected composite type: %v", t))
		}
	default:
		panic(fmt.Sprintf("Invalid underlying type: %v", t))
	}

View on GitHub (pinned to 12126d8942)