{"record":{"id":"5863e9ee181bd260","repo":"vitessio/vitess","slug":"buffer-keyspace-shards-has-overlapping-entries","errorCode":null,"errorMessage":"--buffer-keyspace-shards has overlapping entries (keyspace only vs. keyspace/shard): %v vs. %v Please remove one or the other","messagePattern":"--buffer-keyspace-shards has overlapping entries \\(keyspace only vs\\. keyspace/shard\\): (.+?) vs\\. (.+?) Please remove one or the other","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtgate/buffer/flags.go","lineNumber":97,"sourceCode":"\tif bufferDrainConcurrency < 1 {\n\t\treturn fmt.Errorf(\"--buffer-drain-concurrency must be >= 1 (specified value: %d)\", bufferDrainConcurrency)\n\t}\n\n\tif bufferKeyspaceShards != \"\" && !bufferEnabled {\n\t\treturn fmt.Errorf(\"--buffer-keyspace-shards=%v also requires that --enable_buffer is set\", bufferKeyspaceShards)\n\t}\n\tif bufferEnabled && bufferEnabledDryRun && bufferKeyspaceShards == \"\" {\n\t\treturn 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\")\n\t}\n\n\tkeyspaces, shards := keyspaceShardsToSets(bufferKeyspaceShards)\n\tfor s := range shards {\n\t\tkeyspace, _, err := topoproto.ParseKeyspaceShard(s)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif keyspaces[keyspace] {\n\t\t\treturn fmt.Errorf(\"--buffer-keyspace-shards has overlapping entries (keyspace only vs. keyspace/shard): %v vs. %v Please remove one or the other\", keyspace, s)\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// keyspaceShardsToSets converts a comma separated list of keyspace[/shard]\n// entries to two sets: keyspaces (if the shard is not specified) and shards (if\n// both keyspace and shard is specified).\nfunc keyspaceShardsToSets(list string) (map[string]bool, map[string]bool) {\n\tkeyspaces := make(map[string]bool)\n\tshards := make(map[string]bool)\n\tif list == \"\" {\n\t\treturn keyspaces, shards\n\t}\n\n\tfor item := range strings.SplitSeq(list, \",\") {\n\t\tif strings.Contains(item, \"/\") {","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtgate/buffer/flags.go#L79-L115","documentation":"--buffer-keyspace-shards accepts either whole keyspaces (ks) or specific keyspace/shard pairs (ks/shard). Listing both forms for the same keyspace is ambiguous, so verifyFlags detects the overlap via keyspaceShardsToSets and rejects the configuration.","triggerScenarios":"Setting --buffer-keyspace-shards like 'ks1 ks1/-80' where both the bare keyspace and a shard of the same keyspace appear.","commonSituations":"Incrementally growing the flag from a shard-specific list to a whole keyspace without removing the shard entries; merging flag values from multiple config sources.","solutions":["Keep only the bare keyspace entry to buffer all its shards, e.g. --buffer-keyspace-shards=ks1","Or keep only the explicit shard entries and delete the bare keyspace entry","Re-run/validate with TestVerifyFlags-style verification before rollout"],"exampleFix":"// before\n--buffer-keyspace-shards=commerce commerce/-80\n// after\n--buffer-keyspace-shards=commerce","handlingStrategy":"validation","validationCode":"keyspaces, shards := keyspaceShardsToSets(bufferKeyspaceShards)\nfor s := range shards {\n    keyspace, _, err := topoproto.ParseKeyspaceShard(s)\n    if err != nil { return err }\n    if keyspaces[keyspace] {\n        return fmt.Errorf(\"overlapping entries: %v vs %v\", keyspace, s)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer either whole-keyspace entries or shard lists, never both for the same keyspace","Generate --buffer-keyspace-shards from a single source of truth","Validate the flag value with keyspaceShardsToSets in config linting"],"tags":["vtgate","buffering","flag-validation","configuration"],"backgroundTag":"invalid-flag-value","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}