vitessio/vitess · error

checkpoint information not available in db for %v

Error message

checkpoint information not available in db for %v

What it means

After successfully executing the SELECT on _vt.vreplication for the given uid, exactly one row is expected. Zero (or, given the fetch limit, missing) rows means no checkpoint row exists for that stream id, so the settings cannot be loaded. This is the 'stream was never created or already removed' case.

Source

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

	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)
	}
	stopPos, err := replication.DecodePosition(vrRow.AsString("stop_pos", ""))
	if err != nil {
		return VRSettings{}, fmt.Errorf("failed to parse stop_pos column: %v", err)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Confirm the uid exists: `select * from _vt.vreplication` (via vtctldclient GetWorkflows or VExec) on the correct tablet.
2. Verify you are querying the correct keyspace/tablet (source for the stream, not target).
3. If the row was deleted intentionally, cancel the workflow cleanly and start a new one rather than reusing the old uid.
4. Re-create the workflow (MoveTables/Reshard) if the checkpoint row was lost.

qr, err := dbClient.ExecuteFetch(fmt.Sprintf("SELECT uid FROM _vt.vreplication WHERE uid=%d", uid), 1)
if err != nil { return err }
if len(qr.Rows) == 0 {
	return fmt.Errorf("uid %d does not exist; check `GetWorkflows` before using ReadVRSettings", uid)
}

settings, err := binlogplayer.ReadVRSettings(dbClient, uid)
if err != nil && strings.Contains(err.Error(), "checkpoint information not available") {
	// stream row absent: treat as 'workflow gone', re-enumerate streams
	return listWorkflowsAndRebind(dbClient)
}

When it happens

Trigger: ReadVRSettings called with a uid that has no row in _vt.vreplication: workflow was already completed/pruned, wrong uid passed, target keyspace/tablet queried instead of the source, or the vreplication table was truncated/re-created during recovery.

Common situations: VExec or manual DELETE removed the row while the controller was running; querying the wrong tablet (target instead of source) for the stream; uid mismatch after re-running a workflow that got a new id; workflow migration between shards.

Related errors

• value out of range
• both atomic copy and partial mode cannot be specified for th
• invalid workflow
• multiple source keyspaces for a single workflow
• multiple target keyspaces for a single workflow

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