vitessio/vitess · error

both the dry-run mode and actual buffering is enabled. To av

Error message

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

What it means

verifyFlags validates the vtgate buffering flags. When both --enable_buffer (actual buffering) and dry-run mode are enabled, actual buffering is only allowed for keyspaces/shards explicitly listed in --buffer-keyspace-shards; leaving that flag empty would ambiguously enable real buffering everywhere, so startup fails.

Source

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

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

	return nil
}

// keyspaceShardsToSets converts a comma separated list of keyspace[/shard]
// entries to two sets: keyspaces (if the shard is not specified) and shards (if

View on GitHub (pinned to 01a25a7d17)

Solutions

1. List the keyspace/shard pairs in --buffer-keyspace-shards, e.g. 'ks1/-40, ks1/40-80'
2. Disable dry-run if you intended only dry-run behavior, or disable --enable_buffer if you only wanted dry-run
3. Check other buffering flag validations in the same function (e.g. buffer-keyspace-shards requires --enable_buffer)

Example fix

// before
vtgate --enable_buffer --enable_buffer_dry_run
// after
vtgate --enable_buffer --buffer-keyspace-shards 'commerce/-80,commerce/80-'

if bufferEnabled && bufferEnabledDryRun && bufferKeyspaceShards == "" {
    return errors.New("dry-run + real buffering requires --buffer-keyspace-shards")
}

When it happens

Trigger: Starting vtgate with --enable_buffer=true, --enable_buffer_dry_run=true (or equivalent config), and an empty --buffer-keyspace-shards.

Common situations: Operator turns on real buffering after dry-run testing but forgets to list the target keyspace/shard pairs; copied config from a dry-run example.

Related errors

• failed to load flag for %s: %w
• error creating vtsql proxy: %w
• --buffer-window must be >= 1s (specified value: %v)
• --buffer-window must be <= --buffer-max-failover-duration: %
• --buffer-size must be >= 1 (specified value: %d)

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