vitessio/vitess · error

--buffer-size must be >= 1 (specified value: %d)

Error message

--buffer-size must be >= 1 (specified value: %d)

What it means

The --buffer-size flag controls how many requests the buffer may hold during a failover. verifyFlags requires it to be at least 1; a zero or negative value is nonsensical (no buffering possible) and vtgate refuses to start.

Source

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

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

View on GitHub (pinned to 01a25a7d17)

Solutions

  1. Set --buffer-size to a positive value, e.g. --buffer-size=100 (defaults to 1000)
  2. To disable buffering entirely, do not pass --enable_buffer instead of setting size to 0
  3. Check config templates/env vars for values interpolating to 0

Example fix

// before
vtgate --enable_buffer --buffer-size=0
// after
vtgate --enable_buffer --buffer-size=100
Defensive patterns

Strategy: validation

Validate before calling

if bufferSize < 1 {
    return fmt.Errorf("--buffer-size must be >= 1, got %d", bufferSize)
}

Prevention

When it happens

Trigger: Starting vtgate with --buffer-size=0 or a negative number (often via automation or an env-interpolated value that evaluates to 0).

Common situations: Templated configs where buffer-size comes from a variable defaulting to 0; operator thinking 0 disables buffering (the correct way is to omit --enable_buffer).

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/5c8723ac5fd9a766. Report an issue: GitHub.