--buffer-min-time-between-failovers must be >= 1s (specified

Error message

--buffer-min-time-between-failovers must be >= 1s (specified value: %v)

What it means

--buffer-min-time-between-failovers throttles how often buffering can re-trigger. verifyFlags requires a value of at least 1 second; anything smaller would effectively re-enable buffering instantly after each failover and is rejected at startup.

Source

Thrown at go/vt/vtgate/buffer/flags.go:76

}

func init() {
	servenv.OnParseFor("vtgate", registerFlags)
	servenv.OnParseFor("vtcombo", registerFlags)
}

func verifyFlags() error {
	if bufferWindow < 1*time.Second {
		return fmt.Errorf("--buffer-window must be >= 1s (specified value: %v)", bufferWindow)
	}
	if bufferWindow > bufferMaxFailoverDuration {
		return fmt.Errorf("--buffer-window must be <= --buffer-max-failover-duration: %v vs. %v", bufferWindow, bufferMaxFailoverDuration)
	}
	if bufferSize < 1 {
		return fmt.Errorf("--buffer-size must be >= 1 (specified value: %d)", bufferSize)
	}
	if bufferMinTimeBetweenFailovers < 1*time.Second {
		return fmt.Errorf("--buffer-min-time-between-failovers must be >= 1s (specified value: %v)", bufferMinTimeBetweenFailovers)
	}

	if bufferDrainConcurrency < 1 {
		return fmt.Errorf("--buffer-drain-concurrency must be >= 1 (specified value: %d)", bufferDrainConcurrency)
	}

	if bufferKeyspaceShards != "" && !bufferEnabled {
		return fmt.Errorf("--buffer-keyspace-shards=%v also requires that --enable_buffer is set", bufferKeyspaceShards)
	}
	if bufferEnabled && bufferEnabledDryRun && bufferKeyspaceShards == "" {
		return errors.New("both the dry-run mode and actual buffering is enabled. To avoid ambiguity, keyspaces and shards for actual buffering must be explicitly listed in --buffer-keyspace-shards")
	}

	keyspaces, shards := keyspaceShardsToSets(bufferKeyspaceShards)
	for s := range shards {
		keyspace, _, err := topoproto.ParseKeyspaceShard(s)
		if err != nil {
			return err

View on GitHub (pinned to 01a25a7d17)

Solutions

Set --buffer-min-time-between-failovers to >= 1s (default is 1s)
If failovers are flapping rapidly, address the underlying flapping instead of lowering the throttle
Keep the value aligned with --buffer-window/--buffer-max-failover-duration tuning

Example fix

// before
vtgate --buffer-min-time-between-failovers=0
// after
vtgate --buffer-min-time-between-failovers=1s

Defensive patterns

Strategy: validation

Validate before calling

if bufferMinTimeBetweenFailovers < 1*time.Second {
    return fmt.Errorf("--buffer-min-time-between-failovers must be >= 1s, got %v", bufferMinTimeBetweenFailovers)
}

Prevention

Keep the default (1s) unless you have measured reason to change it
Ensure config tooling emits explicit unit suffixes for durations
Validate duration flags in staging before production rollout

When it happens

Trigger: Starting vtgate with --buffer-min-time-between-failovers set below 1s (e.g. 500ms or 0 via a config default).

Common situations: Operators trying to buffer during rapid flapping failovers shrink this value below the minimum; templated configs defaulting the variable to 0/empty interpreted as 0s.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

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