What causes "SourceConfig.NumHotKeys must be >= 0. Got: %v" in apache/beam?

Set builder.NumHotKeys(n) with n >= 0 (or omit it entirely, defaulting to 0).

SourceConfig.NumHotKeys must be >= 0. Got

Error message

SourceConfig.NumHotKeys must be >= 0. Got: %v

What it means

Build panics when NumHotKeys is negative. Hot-key count is optional (0 means no hot keys) but must not be negative; note the panic message incorrectly prints HotKeyFraction's value, a known quirk in the source.

Solutions

Set builder.NumHotKeys(n) with n >= 0 (or omit it entirely, defaulting to 0).
Check that hot-key and hot-key-fraction config fields are not transposed or negated.
Validate the config's non-negative integer fields before building the source.

Example fix

// before
cfg := synthetic.NewSourceConfig().NumHotKeys(-1).Build()
// after
hotKeys := cfg.HotKeys
if hotKeys < 0 {
    hotKeys = 0
}
cfg2 := synthetic.NewSourceConfig().NumHotKeys(hotKeys).Build()

Defensive patterns

Strategy: validation

Validate before calling

if numHotKeys < 0 {
    return fmt.Errorf("synthetic NumHotKeys must be >= 0, got %d", numHotKeys)
}

Try / catch

defer func() {
    if r := recover(); r != nil {
        err = fmt.Errorf("invalid synthetic source config: %v", r)
    }
}()

Prevention

Remember NumHotKeys defaults to 0; omit it rather than computing negative values.
Clamp skew/hot-key parameters parsed from config to >= 0.
Watch out for swapped NumHotKeys/HotKeyFraction fields when configuring skew.

When it happens

Trigger: Building a SourceConfig with NumHotKeys(-1) or any negative value, typically from a miscomputed or misconfigured integer.

Common situations: Skew simulations where hot-key count or fraction fields were swapped or negated in YAML/flag parsing.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/io/synthetic/source.go:269

// Build constructs the SourceConfig initialized by this builder. It also
// performs error checking on the fields, and panics if any have been set to
// invalid values.
func (b *SourceConfigBuilder) Build() SourceConfig {
	if b.cfg.InitialSplits <= 0 {
		panic(fmt.Sprintf("SourceConfig.InitialSplits must be >= 1. Got: %v", b.cfg.InitialSplits))
	}
	if b.cfg.NumElements <= 0 {
		panic(fmt.Sprintf("SourceConfig.NumElements must be >= 1. Got: %v", b.cfg.NumElements))
	}
	if b.cfg.KeySize <= 0 {
		panic(fmt.Sprintf("SourceConfig.KeySize must be >= 1. Got: %v", b.cfg.KeySize))
	}
	if b.cfg.ValueSize <= 0 {
		panic(fmt.Sprintf("SourceConfig.ValueSize must be >= 1. Got: %v", b.cfg.ValueSize))
	}
	if b.cfg.NumHotKeys < 0 {
		panic(fmt.Sprintf("SourceConfig.NumHotKeys must be >= 0. Got: %v", b.cfg.HotKeyFraction))
	}
	if b.cfg.HotKeyFraction < 0 || b.cfg.HotKeyFraction > 1 {
		panic(fmt.Sprintf("SourceConfig.HotKeyFraction must be a floating point number from 0 and 1. Got: %v", b.cfg.NumHotKeys))
	}
	return b.cfg
}

// BuildFromJSON constructs the SourceConfig by populating it with the parsed
// JSON. Panics if there is an error in the syntax of the JSON or if the input
// contains unknown object keys.
//
// An example of valid JSON object:
//
//	{
//		 "num_records": 5,
//		 "key_size": 5,
//		 "value_size": 5,
//		 "num_hot_keys": 5,

View on GitHub (pinned to 12126d8942)