{"record":{"id":"bfb8716869858735","repo":"vitessio/vitess","slug":"failed-to-instantiate-throttler-v","errorCode":null,"errorMessage":"failed to instantiate throttler: %v","messagePattern":"failed to instantiate throttler: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/binlog/binlogplayer/binlog_player.go","lineNumber":296,"sourceCode":"func (blp *BinlogPlayer) applyEvents(ctx context.Context) error {\n\t// Read starting values for vreplication.\n\tsettings, err := ReadVRSettings(blp.dbClient, blp.uid)\n\tif err != nil {\n\t\tlog.Error(fmt.Sprint(err))\n\t\treturn err\n\t}\n\n\tblp.position = settings.StartPos\n\tblp.stopPosition = settings.StopPos\n\tt, err := throttler.NewThrottler(\n\t\tfmt.Sprintf(\"BinlogPlayer/%d\", blp.uid),\n\t\t\"transactions\",\n\t\t1, /* threadCount */\n\t\tsettings.MaxTPS,\n\t\tsettings.MaxReplicationLag,\n\t)\n\tif err != nil {\n\t\terr := fmt.Errorf(\"failed to instantiate throttler: %v\", err)\n\t\tlog.Error(fmt.Sprint(err))\n\t\treturn err\n\t}\n\tdefer t.Close()\n\n\t// Log the mode of operation and when the player stops.\n\tif len(blp.tables) > 0 {\n\t\tlog.Info(fmt.Sprintf(\"BinlogPlayer client %v for tables %v starting @ '%v', server: %v\", blp.uid,\n\t\t\tblp.tables,\n\t\t\tblp.position,\n\t\t\tblp.tablet))\n\t} else {\n\t\tlog.Info(fmt.Sprintf(\"BinlogPlayer client %v for keyrange '%v-%v' starting @ '%v', server: %v\", blp.uid,\n\t\t\thex.EncodeToString(blp.keyRange.GetStart()),\n\t\t\thex.EncodeToString(blp.keyRange.GetEnd()),\n\t\t\tblp.position,\n\t\t\tblp.tablet))\n\t}","sourceCodeStart":278,"sourceCodeEnd":314,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/binlog/binlogplayer/binlog_player.go#L278-L314","documentation":"The binlog player (filtered replication / vreplication player) creates an internal throttler to cap TPS and replication lag before applying events. If throttler.New fails (invalid settings), applyEvents returns this wrapped error and the player stops.","triggerScenarios":"ApplyBinlogEvents -> applyEvents with blpSettings whose MaxTPS or MaxReplicationLag values are invalid/nonsensical, causing throttler.New to return an error.","commonSituations":"Bad vr_cluster / BinlogSource settings in a VReplicationWorkflow spec (e.g. malformed stopAtCopy or throttler options), operator passing zero/negative throttler parameters programmatically.","solutions":["Validate the binlog player settings (MaxTPS, MaxReplicationLag) in the VReplication workflow spec and correct invalid values","Read the inner error (%v) — it names the exact throttler validation failure","Update the workflow via vtctld (UpdateVReplicationWorkflow) with fixed throttler parameters","If using custom code, pass valid non-negative MaxTPS/MaxReplicationLag"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if settings.MaxTPS < 0 || settings.MaxReplicationLag < 0 {\n    return fmt.Errorf(\"invalid throttler settings: MaxTPS=%d MaxReplicationLag=%d\", settings.MaxTPS, settings.MaxReplicationLag)\n}","typeGuard":null,"tryCatchPattern":"err := blp.ApplyBinlogEvents(ctx)\nif err != nil && strings.Contains(err.Error(), \"failed to instantiate throttler\") {\n    // correct blpSettings and re-create the binlog player\n}","preventionTips":["Validate throttler fields in workflow specs before applying","Never pass negative TPS/lag values","Test workflow specs with vtctldclient dry validation","Keep vitess operator and vttablet versions aligned"],"tags":["throttler","vreplication","configuration"],"backgroundTag":"throttler-config-invalid","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}