vitessio/vitess · error

failed to instantiate throttler: %v

Error message

failed to instantiate throttler: %v

What it means

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.

Source

Thrown at go/vt/binlog/binlogplayer/binlog_player.go:296

func (blp *BinlogPlayer) applyEvents(ctx context.Context) error {
	// Read starting values for vreplication.
	settings, err := ReadVRSettings(blp.dbClient, blp.uid)
	if err != nil {
		log.Error(fmt.Sprint(err))
		return err
	}

	blp.position = settings.StartPos
	blp.stopPosition = settings.StopPos
	t, err := throttler.NewThrottler(
		fmt.Sprintf("BinlogPlayer/%d", blp.uid),
		"transactions",
		1, /* threadCount */
		settings.MaxTPS,
		settings.MaxReplicationLag,
	)
	if err != nil {
		err := fmt.Errorf("failed to instantiate throttler: %v", err)
		log.Error(fmt.Sprint(err))
		return err
	}
	defer t.Close()

	// Log the mode of operation and when the player stops.
	if len(blp.tables) > 0 {
		log.Info(fmt.Sprintf("BinlogPlayer client %v for tables %v starting @ '%v', server: %v", blp.uid,
			blp.tables,
			blp.position,
			blp.tablet))
	} else {
		log.Info(fmt.Sprintf("BinlogPlayer client %v for keyrange '%v-%v' starting @ '%v', server: %v", blp.uid,
			hex.EncodeToString(blp.keyRange.GetStart()),
			hex.EncodeToString(blp.keyRange.GetEnd()),
			blp.position,
			blp.tablet))
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Validate the binlog player settings (MaxTPS, MaxReplicationLag) in the VReplication workflow spec and correct invalid values
2. Read the inner error (%v) — it names the exact throttler validation failure
3. Update the workflow via vtctld (UpdateVReplicationWorkflow) with fixed throttler parameters
4. If using custom code, pass valid non-negative MaxTPS/MaxReplicationLag

if settings.MaxTPS < 0 || settings.MaxReplicationLag < 0 {
    return fmt.Errorf("invalid throttler settings: MaxTPS=%d MaxReplicationLag=%d", settings.MaxTPS, settings.MaxReplicationLag)
}

err := blp.ApplyBinlogEvents(ctx)
if err != nil && strings.Contains(err.Error(), "failed to instantiate throttler") {
    // correct blpSettings and re-create the binlog player
}

When it happens

Trigger: ApplyBinlogEvents -> applyEvents with blpSettings whose MaxTPS or MaxReplicationLag values are invalid/nonsensical, causing throttler.New to return an error.

Common situations: Bad vr_cluster / BinlogSource settings in a VReplicationWorkflow spec (e.g. malformed stopAtCopy or throttler options), operator passing zero/negative throttler parameters programmatically.

Related errors

• stream needs a position or a table to copy
• partial row image encountered: ensure binlog_row_image is se
• no binlog player client factory named %v
• registerThrottler(): throttler with name '%v' is already reg
• throttler: %v does not exist

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