{"record":{"id":"06d72bea03df6701","repo":"vitessio/vitess","slug":"buffer-window-must-be-1s-specified-value-v","errorCode":null,"errorMessage":"--buffer-window must be >= 1s (specified value: %v)","messagePattern":"--buffer-window must be >= 1s \\(specified value: (.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtgate/buffer/flags.go","lineNumber":67,"sourceCode":"\tutils.SetFlagBoolVar(fs, &bufferEnabledDryRun, \"enable-buffer-dry-run\", false, \"Detect and log failover events, but do not actually buffer requests.\")\n\n\tutils.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).\")\n\tutils.SetFlagIntVar(fs, &bufferSize, \"buffer-size\", 1000, \"Maximum number of buffered requests in flight (across all ongoing failovers).\")\n\tutils.SetFlagDurationVar(fs, &bufferMaxFailoverDuration, \"buffer-max-failover-duration\", 20*time.Second, \"Stop buffering completely if a failover takes longer than this duration.\")\n\tutils.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.\")\n\n\tutils.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.\")\n\tutils.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.\")\n}\n\nfunc init() {\n\tservenv.OnParseFor(\"vtgate\", registerFlags)\n\tservenv.OnParseFor(\"vtcombo\", registerFlags)\n}\n\nfunc verifyFlags() error {\n\tif bufferWindow < 1*time.Second {\n\t\treturn fmt.Errorf(\"--buffer-window must be >= 1s (specified value: %v)\", bufferWindow)\n\t}\n\tif bufferWindow > bufferMaxFailoverDuration {\n\t\treturn fmt.Errorf(\"--buffer-window must be <= --buffer-max-failover-duration: %v vs. %v\", bufferWindow, bufferMaxFailoverDuration)\n\t}\n\tif bufferSize < 1 {\n\t\treturn fmt.Errorf(\"--buffer-size must be >= 1 (specified value: %d)\", bufferSize)\n\t}\n\tif bufferMinTimeBetweenFailovers < 1*time.Second {\n\t\treturn fmt.Errorf(\"--buffer-min-time-between-failovers must be >= 1s (specified value: %v)\", bufferMinTimeBetweenFailovers)\n\t}\n\n\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}","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtgate/buffer/flags.go#L49-L85","documentation":"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.","triggerScenarios":"Starting vtgate (or vtcombo) with --buffer-window set to a value < 1s, e.g. --buffer-window=500ms, while buffering flags are being parsed.","commonSituations":"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).","solutions":["Set --buffer-window to at least 1s, e.g. --buffer-window=30s","If you need faster reactivity, keep the window >= 1s and tune --buffer-max-failover-duration instead","Verify with a dry run: run verifyFlags via TestVerifyFlags or start vtgate with --buffer-enabled-dry-run to sanity-check flags"],"exampleFix":"// before\nvtgate --buffer-window=500ms ...\n// after\nvtgate --buffer-window=1s ...","handlingStrategy":"validation","validationCode":"if bufferWindow < 1*time.Second {\n    return fmt.Errorf(\"--buffer-window must be >= 1s, got %v\", bufferWindow)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass duration values with explicit units (30s, 1m)","Pin buffer flag values in config management rather than ad-hoc CLI edits","Run vtgate flag verification (TestVerifyFlags) in CI for your deploy configs"],"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-08T05:18:18.240Z"}