SourceConfig.HotKeyFraction must be a floating point number…

Error message

SourceConfig.HotKeyFraction must be a floating point number from 0 and 1. Got: %v

What it means

SourceConfigBuilder.Build() in the Beam Go synthetic source panics when HotKeyFraction is outside the [0,1] range. The synthetic source uses this fraction to control how many records come from hot keys, so a fraction below 0 or above 1 is meaningless. Note the source region shows a copy-paste bug in the library itself: the panic message formats cfg.NumHotKeys instead of cfg.HotKeyFraction, so the reported value in the message will be wrong.

Solutions

Clamp or validate HotKeyFraction to [0,1] before calling Build(), e.g. if f < 0 || f > 1 { return error }.
If the value came from a percentage, divide by 100 (50 -> 0.5).
Check that you did not accidentally set HotKeyFraction where you meant NumHotKeys (or vice versa), since the panic message itself misreports the value due to a formatting bug.

Example fix

// before
b.HotKeyFraction(50) // meant 50%
// after
b.HotKeyFraction(0.5)

Defensive patterns

Strategy: validation

Validate before calling

if cfg.HotKeyFraction < 0 || cfg.HotKeyFraction > 1 {
    return fmt.Errorf("HotKeyFraction must be in [0,1], got %v", cfg.HotKeyFraction)
}

Prevention

Validate fractions in your config-loading layer before building pipeline components.
Remember percentages must be converted to fractions (50 -> 0.5).
Write a unit test for every synthetic-source config template.

When it happens

Trigger: Calling SourceConfigBuilder.Build() after setting HotKeyFraction to a negative value or a value greater than 1 (e.g. via builder.HotKeyFraction(1.5) or negative values in JSON-driven configs).

Common situations: Passing a percentage like 50 instead of 0.5; computing a fraction with integer division that yields a bad value; hand-writing synthetic source JSON in a pipeline template with an out-of-range fraction; typos swapping NumHotKeys and HotKeyFraction fields.

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/9ec699a7d08b0f8a. Report an issue: GitHub.

Appendix: source

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

// 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,
//	}
func (b *SourceConfigBuilder) BuildFromJSON(jsonData []byte) SourceConfig {
	decoder := json.NewDecoder(bytes.NewReader(jsonData))

View on GitHub (pinned to 12126d8942)