vitessio/vitess · error

error reading VReplication settings: %v

Error message

error reading VReplication settings: %v

What it means

readSettings loads the vreplication row settings (workflow type, filters, options) via binlogplayer.ReadVRSettings. When that read or parse fails, the error is wrapped with this message so operators know the VReplication engine could not load its configuration from _vt.vreplication. Without valid settings the vreplicator cannot start or configure itself.

Source

Thrown at go/vt/vttablet/tabletmanager/vreplication/vreplicator.go:518

		// Reconcile the exported state metric with the row we just read
		// from _vt.vreplication, which is the source of truth. setState()
		// advances stats.State before its DB UPDATE is sent, while vr.state
		// is only updated after a successful write; when that UPDATE fails
		// (e.g. the target is read-only during a reparent) the metric is
		// left out of sync with the persisted row. Re-syncing it here on
		// every successful read recovers the metric once the stream
		// resumes. vr.state is deliberately left alone: it already matches
		// the persisted row, and overwriting it would break the state
		// transitions Replicate() relies on. See #20012.
		vr.stats.State.Store(settings.State.String())
	}
	return settings, numTablesToCopy, err
}

func (vr *vreplicator) readSettings(ctx context.Context, dbClient *vdbClient) (settings binlogplayer.VRSettings, numTablesToCopy int64, err error) {
	settings, err = binlogplayer.ReadVRSettings(dbClient, vr.id)
	if err != nil {
		return settings, numTablesToCopy, fmt.Errorf("error reading VReplication settings: %v", err)
	}

	query := fmt.Sprintf("select count(distinct table_name) from _vt.copy_state where vrepl_id=%d", vr.id)
	qr, err := vr.dbClient.ExecuteFetch(query, maxRows)
	if err != nil {
		return settings, numTablesToCopy, err
	}
	if len(qr.Rows) == 0 || len(qr.Rows[0]) == 0 {
		return settings, numTablesToCopy, fmt.Errorf("unexpected result from %s: %v", query, qr)
	}
	numTablesToCopy, err = qr.Rows[0][0].ToCastInt64()
	if err != nil {
		return settings, numTablesToCopy, err
	}
	return settings, numTablesToCopy, nil
}

func (vr *vreplicator) setMessage(message string) (err error) {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the wrapped cause (%v suffix) — it names the actual MySQL/query failure; run the settings query manually against _vt.vreplication for this vr.id.
2. Verify the _vt.vreplication row exists and its fields (source, message, options) are valid JSON/not corrupt.
3. Confirm MySQL connectivity from the tablet and that the _vt schema is present and at the expected version.
4. If the workflow is dead/garbage, delete the row with VReplicationExec or vtctldclient and re-create the workflow (MoveTables/Reshard).

Example fix

// before: row manually edited, options column is invalid JSON
// after: recreate the workflow cleanly
// vtctldclient MoveTables --target-keyspace=customer ...  (after cleaning the stale row)
// DELETE FROM _vt.vreplication WHERE id=<bad_id>; -- via VReplicationExec, then re-run the workflow

// Before relying on the stream, check the settings row is readable and well-formed:
// SELECT id, workflow, source, options FROM _vt.vreplication WHERE id = <id>;
// Validate `options` parses as JSON if non-empty.

err := vr.readSettings(ctx, dbClient)
if err != nil {
	log.Warn("vreplication settings unreadable; recreating workflow", slog.Any("error", err))
	// fall back to re-creating the workflow via vtctldclient
}

When it happens

Trigger: binlogplayer.ReadVRSettings returns an error, e.g. the query 'select ... from _vt.vreplication where id=<vr.id>' fails, the row is missing/corrupt, or settings fields (charset, options blob) fail to unmarshal.

Common situations: The _vt.vreplication row was manually edited or corrupted; the target tablet cannot reach MySQL; a schema migration of _vt.vreplication left the row in an unexpected shape; the workflow was deleted mid-flight while the vreplicator was loading.

Related errors

• partial row image encountered: ensure binlog_row_image is se
• direct DDL is disabled
• online DDL is disabled
• stream needs a position or a table to copy
• failed to instantiate throttler: %v

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