apache/beam · error

SourceConfig.KeySize must be >= 1. Got

Error message

SourceConfig.KeySize must be >= 1. Got: %v

What it means

Panic raised by synthetic SourceConfigBuilder.Build when cfg.KeySize is zero or negative. KeySize controls generated key byte length; Build performs eager bounds checks on all fields and panics on this invalid value at configuration time.

Solutions

1. Call builder.KeySize(n) with n >= 1 before Build().
2. Clamp the key-size config value to a minimum of 1.
3. Complete the builder chain so all size fields are set.

Example fix

// before
cfg := synthetic.NewSourceConfig().NumElements(100).ValueSize(16).Build()
// after
cfg := synthetic.NewSourceConfig().NumElements(100).KeySize(8).ValueSize(16).Build()

if keySize < 1 {
    return fmt.Errorf("synthetic KeySize must be >= 1, got %d", keySize)
}

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

When it happens

Trigger: Building a SourceConfig without KeySize(n) or with KeySize(0) / a negative value.

Common situations: Benchmarks parameterizing key size from config with a 0 default, or incomplete builder chains copied from examples.

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

• SourceConfig.InitialSplits must be >= 1. Got
• SourceConfig.NumElements must be >= 1. Got
• SourceConfig.NumHotKeys must be >= 0. Got
• SourceConfig.ValueSize must be >= 1. Got
• capacity of cache cannot be negative, got

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

Appendix: source

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

//
// Valid values are floating point numbers from 0 to 1.
func (b *SourceConfigBuilder) HotKeyFraction(val float64) *SourceConfigBuilder {
	b.cfg.HotKeyFraction = val
	return b
}

// 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:

View on GitHub (pinned to 12126d8942)