apache/beam · error

Invalid number of components for ShardedKey

Error message

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

What it means

typex.New validates ShardedKey types: a ShardedKey must have exactly one component. When len(components) != 1, New panics with this message including the type and its components. The SDK uses this to guarantee the internal invariant that ShardedKey always carries a single underlying value type.

Solutions

1. Pass exactly one component: typex.New(typex.ShardedKeyType, singleType).
2. If you intended a keyed pair, wrap the pair in a KV first: typex.New(typex.ShardedKeyType, typex.NewKV(k, v)) is still one component.
3. If you meant a multi-component composite, use a different type class (e.g. CoGBK or a struct-based type) instead of ShardedKey.

Example fix

// before
typex.New(typex.ShardedKeyType, keyType, valueType)
// after
typex.New(typex.ShardedKeyType, typex.NewKV(keyType, valueType))

func validShardedKey(cs []typex.FullType) bool { return len(cs) == 1 }

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
}

When it happens

Trigger: Calling typex.New with a Composite of class ShardedKeyType and zero or two-plus components, e.g. typex.New(typex.ShardedKeyType) or typex.New(typex.ShardedKeyType, t1, t2). Reached via New's public callers: Prefix, CoGroupByKey, CombinePerKey, CombineGlobally, Flatten, GroupByKey.

Common situations: Hand-constructing sharded-key types for use with WithShardedKey-style transforms and accidentally passing the key and value separately instead of a single KV component; copy-paste from KV construction code that takes multiple components.

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

• Invalid to nest composite inside ShardedKey
• Invalid to nest composites inside CoGBK
• Invalid underlying type
• nil type at index
• Unexpected composite type

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

Appendix: source

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

				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))
	}
}

// NOTE(herohde) 1/26/2018: we allow nested KV types and coders to support the
// CoGBK translation (using KV<K,KV<int,[]byte>> to encode keyed raw union values)
// and potentially other uses. We do not have a reasonable way to emit nested KV
// values, so user functions are still limited to non-nested KVs. Universally-typed
// KV-values might be simple to allow, for example.

View on GitHub (pinned to 12126d8942)