vitessio/vitess · error

--buffer-window must be >= 1s (specified value: %v)

Error message

--buffer-window must be >= 1s (specified value: %v)

What it means

vtgate's buffering feature refuses to start when --buffer-window is set below the 1-second minimum. verifyFlags validates the flag combination during flag parsing (via NewConfigFromFlags); a window shorter than 1s is considered useless/unsafe for failover buffering, so the process exits with this error instead of starting with bad settings.

Source

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

	utils.SetFlagBoolVar(fs, &bufferEnabledDryRun, "enable-buffer-dry-run", false, "Detect and log failover events, but do not actually buffer requests.")

	utils.SetFlagDurationVar(fs, &bufferWindow, "buffer-window", 10*time.Second, "Duration for how long a request should be buffered at most (should not be larger than --buffer-max-failover-duration).")
	utils.SetFlagIntVar(fs, &bufferSize, "buffer-size", 1000, "Maximum number of buffered requests in flight (across all ongoing failovers).")
	utils.SetFlagDurationVar(fs, &bufferMaxFailoverDuration, "buffer-max-failover-duration", 20*time.Second, "Stop buffering completely if a failover takes longer than this duration.")
	utils.SetFlagDurationVar(fs, &bufferMinTimeBetweenFailovers, "buffer-min-time-between-failovers", 1*time.Minute, "Minimum time between the end of a failover and the start of the next one (tracked per shard). Faster consecutive failovers will not trigger buffering.")

	utils.SetFlagIntVar(fs, &bufferDrainConcurrency, "buffer-drain-concurrency", 1, "Maximum number of requests retried simultaneously. More concurrency will increase the load on the PRIMARY vttablet when draining the buffer.")
	utils.SetFlagStringVar(fs, &bufferKeyspaceShards, "buffer-keyspace-shards", "", "If not empty, limit buffering to these entries (comma separated). Entry format: keyspace or keyspace/shard. Requires --enable_buffer=true.")
}

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)
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Set --buffer-window to at least 1s, e.g. --buffer-window=30s
2. If you need faster reactivity, keep the window >= 1s and tune --buffer-max-failover-duration instead
3. Verify with a dry run: run verifyFlags via TestVerifyFlags or start vtgate with --buffer-enabled-dry-run to sanity-check flags

Example fix

// before
vtgate --buffer-window=500ms ...
// after
vtgate --buffer-window=1s ...

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

When it happens

Trigger: Starting vtgate (or vtcombo) with --buffer-window set to a value < 1s, e.g. --buffer-window=500ms, while buffering flags are being parsed.

Common situations: Operators tuning buffering for very short failovers copy an example and shrink --buffer-window below 1s; unit-test configs that set small windows; mistaking the unit (e.g. passing 0.5 without a duration suffix).

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

• --buffer-window must be <= --buffer-max-failover-duration: %
• --buffer-size must be >= 1 (specified value: %d)
• --buffer-min-time-between-failovers must be >= 1s (specified
• --buffer-drain-concurrency must be >= 1 (specified value: %d
• --buffer-keyspace-shards=%v also requires that --enable_buff

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