What causes "maxRate must be >= 0: %v" in vitessio/vitess?

Pass maxRate >= 0; use 0 or the appropriate disabled sentinel for 'no explicit limit'.

maxRate must be >= 0: %v

Error message

maxRate must be >= 0: %v

What it means

Returned by throttler rate config validation when maxRate is negative; a negative maximum rate is meaningless and the value must be zero or positive.

Source

Thrown at go/vt/throttler/throttler.go:166

func NewThrottlerFromConfig(name, unit string, threadCount int, maxRateModuleMaxRate int64, maxReplicationLagModuleConfig MaxReplicationLagModuleConfig, nowFunc func() time.Time) (Throttler, error) {
	return newThrottlerFromConfig(GlobalManager, name, unit, threadCount, maxRateModuleMaxRate, maxReplicationLagModuleConfig, nowFunc)
}

func newThrottler(manager *managerImpl, name, unit string, threadCount int, maxRate, maxReplicationLag int64, nowFunc func() time.Time) (Throttler, error) {
	config := NewMaxReplicationLagModuleConfig(maxReplicationLag)
	config.MaxReplicationLagSec = maxReplicationLag

	return newThrottlerFromConfig(manager, name, unit, threadCount, maxRate, config, nowFunc)
}

func newThrottlerFromConfig(manager *managerImpl, name, unit string, threadCount int, maxRateModuleMaxRate int64, maxReplicationLagModuleConfig MaxReplicationLagModuleConfig, nowFunc func() time.Time) (Throttler, error) {
	err := maxReplicationLagModuleConfig.Verify()
	if err != nil {
		return nil, fmt.Errorf("invalid max replication lag config: %w", err)
	}
	if maxRateModuleMaxRate < 0 {
		return nil, fmt.Errorf("maxRate must be >= 0: %v", maxRateModuleMaxRate)
	}

	// Enable the configured modules.
	maxRateModule := NewMaxRateModule(maxRateModuleMaxRate)
	actualRateHistory := newAggregatedIntervalHistory(1024, 1*time.Second, threadCount)
	maxReplicationLagModule, err := NewMaxReplicationLagModule(maxReplicationLagModuleConfig, actualRateHistory, nowFunc)
	if err != nil {
		return nil, err
	}

	modules := make([]Module, 0, 2)
	modules = append(modules, maxRateModule)
	modules = append(modules, maxReplicationLagModule)

	// Start each module (which might start own Go routines).
	rateUpdateChan := make(chan struct{}, 10)
	for _, m := range modules {
		m.Start(rateUpdateChan)

View on GitHub (pinned to 01a25a7d17)

Solutions

Pass maxRate >= 0; use 0 or the appropriate disabled sentinel for 'no explicit limit'.
Clamp or validate the rate before calling NewThrottlerFromConfig (e.g. if maxRate < 0 { maxRate = 0 }).
Check the flag/config source for a stray negative sign.

Example fix

// before
maxRate := -1 // meant unlimited
// after
maxRate := 0

Defensive patterns

Strategy: validation

Validate before calling

if maxRate < 0 {
    return errors.New("maxRate must be >= 0")
}

Try / catch

t, err := throttler.NewThrottlerFromConfig(mgr, name, unit, threads, maxRate, cfg, nowFunc)
if err != nil {
    return err
}

Prevention

Clamp parsed max-rate flags to >= 0.
Use 0 as the 'unset' value, never negative numbers.
Validate numeric flags with bounds checking in PreRunE-style setup.

When it happens

Trigger: NewThrottlerFromConfig or newThrottler called with maxRate < 0, e.g. parsing a negative value from a flag or config field like --max-rate.

Common situations: Sign errors when computing rates programmatically; misparsed flags; template/config typo producing -1 for 'unlimited' instead of 0.

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

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/46f5cca92f6b4e8d. Report an issue: GitHub.