apache/beam · error

SourceConfig.InitialSplits must be >= 1. Got

Error message

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

What it means

SourceConfigBuilder.Build validates the synthetic source configuration and panics if InitialSplits is zero or negative. The synthetic source pre-partitions generated data, which requires at least one split.

Solutions

1. Call builder.InitialSplits(n) with n >= 1 before Build().
2. Clamp or default the splits value from your config to at least 1.
3. Add a validation step on the config object before constructing the builder.

Example fix

// before
cfg := synthetic.NewSourceConfig().NumElements(1000).Build()
// after
cfg := synthetic.NewSourceConfig().NumElements(1000).InitialSplits(4).Build()

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

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

When it happens

Trigger: Building a synthetic source via NewSourceConfig builder without calling InitialSplits(n) (zero value), or explicitly setting InitialSplits(0) / a negative number.

Common situations: Benchmark/test harnesses deriving split count from config or flags that default to 0, or copy-pasted configs missing the builder call.

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.KeySize 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/ae5400810b56e6f4. Report an issue: GitHub.

Appendix: source

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

func (b *SourceConfigBuilder) NumHotKeys(val int) *SourceConfigBuilder {
	b.cfg.NumHotKeys = int64(val)
	return b
}

// HotKeyFraction determines the value of hot key fraction.
//
// 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
}

View on GitHub (pinned to 12126d8942)