What causes "--buffer-drain-concurrency must be >= 1 (specified value: %d)" in vitessio/vitess?

Set --buffer-drain-concurrency to >= 1 (default is 1)

--buffer-drain-concurrency must be >= 1 (specified value: %d

Error message

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

What it means

--buffer-drain-concurrency is the number of goroutines used to drain buffered requests after a failover. verifyFlags requires at least 1; zero or negative values would mean buffered requests are never drained, so vtgate rejects the configuration at startup.

Source

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

	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
		}
		if keyspaces[keyspace] {
			return fmt.Errorf("--buffer-keyspace-shards has overlapping entries (keyspace only vs. keyspace/shard): %v vs. %v Please remove one or the other", keyspace, s)
		}

View on GitHub (pinned to 01a25a7d17)

Solutions

Set --buffer-drain-concurrency to >= 1 (default is 1)
To disable buffering, omit --enable_buffer instead of zeroing the concurrency
Audit config templating/env vars that resolve to 0

Example fix

// before
vtgate --enable_buffer --buffer-drain-concurrency=0
// after
vtgate --enable_buffer --buffer-drain-concurrency=1

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Keep buffer-drain-concurrency at 1+ ; scale up for faster drains, never to 0
Interpolate integers from config with strict non-zero validation
Add a startup smoke test exercising buffering flags

When it happens

Trigger: Starting vtgate with --buffer-drain-concurrency=0 or negative, typically from an interpolated config value or a misunderstood '0 means default' assumption.

Common situations: Templating tools emitting 0 for unset variables; operators assuming 0 disables draining rather than omitting buffering altogether.

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