vitessio/vitess · error

error %v in selecting vreplication settings %v

Error message

error %v in selecting vreplication settings %v

What it means

ReadVRSettings reads a vreplication stream's row (from _vt.vreplication via GetWorkflowQuery) to load its settings. This error wraps a low-level MySQL/dbclient failure encountered while executing that SELECT, including the underlying error and the exact query. It means the checkpoint row could not be fetched at all, not that the row was missing or malformed.

Source

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

type VRSettings struct {
	StartPos           replication.Position
	StopPos            replication.Position
	MaxTPS             int64
	MaxReplicationLag  int64
	State              binlogdatapb.VReplicationWorkflowState
	WorkflowType       binlogdatapb.VReplicationWorkflowType
	WorkflowSubType    binlogdatapb.VReplicationWorkflowSubType
	WorkflowName       string
	DeferSecondaryKeys bool
	WorkflowOptions    *vtctldata.WorkflowOptions
}

// ReadVRSettings retrieves the settings for a vreplication stream.
func ReadVRSettings(dbClient DBClient, uid int32) (VRSettings, error) {
	query := fmt.Sprintf(GetWorkflowQuery, uid)
	qr, err := dbClient.ExecuteFetch(query, 1)
	if err != nil {
		return VRSettings{}, fmt.Errorf("error %v in selecting vreplication settings %v", err, query)
	}

	if len(qr.Rows) != 1 {
		return VRSettings{}, fmt.Errorf("checkpoint information not available in db for %v", uid)
	}
	vrRow := qr.Named().Row()

	maxTPS, err := vrRow.ToInt64("max_tps")
	if err != nil {
		return VRSettings{}, fmt.Errorf("failed to parse max_tps column: %v", err)
	}
	maxReplicationLag, err := vrRow.ToInt64("max_replication_lag")
	if err != nil {
		return VRSettings{}, fmt.Errorf("failed to parse max_replication_lag column: %v", err)
	}
	startPos, err := DecodePosition(vrRow.AsString("pos", ""))
	if err != nil {
		return VRSettings{}, fmt.Errorf("failed to parse pos column: %v", err)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check connectivity between the vttablet and its backing MySQL instance and verify MySQL is up.
2. Verify the _vt.vreplication table exists on the target (run the VTGate/tablet schema init or `vttablet` startup migrations).
3. Inspect the wrapped inner error (%v after the message) for the MySQL error code and act on it specifically.
4. Retry the workflow/ctl command; transient network errors often resolve on the next controller tick.

Example fix

// before: generic error hides root cause
return VRSettings{}, fmt.Errorf("error %v in selecting vreplication settings %v", err, query)
// after: wrap with context so the MySQL code is preserved
return VRSettings{}, vterrors.Wrapf(err, "selecting vreplication settings for uid %d (query: %s)", uid, query)

// Before relying on the stream, verify reachability
if err := dbClient.ExecuteFetch("SELECT 1 FROM _vt.vreplication LIMIT 1", 1); err != nil {
	return fmt.Errorf("vreplication table not reachable: %w", err)
}

settings, err := binlogplayer.ReadVRSettings(dbClient, uid)
if err != nil {
	if strings.Contains(err.Error(), "in selecting vreplication settings") {
		// transient DB issue: log and retry with backoff
		return retryWithBackoff(ctx, func() error { _, err = binlogplayer.ReadVRSettings(dbClient, uid); return err })
	}
	return err
}

When it happens

Trigger: dbClient.ExecuteFetch(GetWorkflowQuery, 1) returns an error while ReadVRSettings is called (directly or via applyEvents, initTablesForCopy, catchup, fastForward, readSettings): DB connection refused/dropped, table _vt.vreplication missing, bad credentials, query timeout, or the tablet/dbclient is not in a state to serve the query.

Common situations: VReplication workflow (MoveTables/Reshard) controller failing to reach the target tablet's MySQL; _vt schema not initialized on a newly restored target; MySQL restarted mid-copy; network partition between vttablet and MySQL.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• could not set message: %v: %v
• recovery.IsRecoveryDisabled(): %v
• partial row image encountered: ensure binlog_row_image is se
• failed to set @source_binlog_checksum=@@global.binlog_checks
• failed to send the ComBinlogDump command: %v

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