vitessio/vitess · error

vdiff with UUID %s not found on tablet %s

Error message

vdiff with UUID %s not found on tablet %s

What it means

For a ResumeAction (or any non-create action) where the record query indicated a row existed (recordFound true path handled elsewhere), Vitess errors if no vdiff record with the given UUID exists on this tablet. Each tablet stores its own vdiff rows, so a UUID valid on one tablet may be missing on another.

Source

Thrown at go/vt/vttablet/tabletmanager/vdiff/action.go:235

			sqltypes.StringBindVariable(string(optionsJSON)),
			sqltypes.StringBindVariable(vde.thisTablet.Shard),
			sqltypes.StringBindVariable(topoproto.TabletDbName(vde.thisTablet)),
			sqltypes.StringBindVariable(req.VdiffUuid),
		)
		if err != nil {
			return err
		}
		if qr, err = dbClient.ExecuteFetch(query, 1); err != nil {
			return err
		}
		if qr.InsertID == 0 {
			return fmt.Errorf("unable to create vdiff for UUID %s on tablet %s (%w)",
				req.VdiffUuid, topoproto.TabletAliasString(vde.thisTablet.Alias), err)
		}
		resp.Id = int64(qr.InsertID)
	} else {
		if !recordFound {
			return fmt.Errorf("vdiff with UUID %s not found on tablet %s",
				req.VdiffUuid, topoproto.TabletAliasString(vde.thisTablet.Alias))
		}
		if resp.Id, err = qr.Named().Row().ToInt64("id"); err != nil {
			return fmt.Errorf("vdiff found with invalid id on tablet %s: %w",
				topoproto.TabletAliasString(vde.thisTablet.Alias), err)
		}
		execResume := func(query string) (rowsAffected uint64, err error) {
			query, err = sqlparser.ParseAndBind(query,
				sqltypes.StringBindVariable(req.VdiffUuid),
				sqltypes.StringBindVariable(vde.dbName),
			)
			if err != nil {
				return 0, err
			}
			if qr, err = dbClient.ExecuteFetch(query, 1); err != nil {
				return 0, err
			}
			return qr.RowsAffected, nil

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Run vdiff show to list UUIDs present on this tablet
2. Create the vdiff first if it never existed, then resume
3. Target the correct tablet with --tablet-uuid where the vdiff record lives
4. If the record was deleted intentionally, start a fresh vdiff with a new UUID

Example fix

// before
vtctldclient VDiff resume --tablet-uuid tablet-a --uuid unknown-uuid
// after: create first, then resume
vtctldclient VDiff create --tablet-uuid tablet-a
vtctldclient VDiff resume --tablet-uuid tablet-a

qr, _ := dbClient.ExecuteFetch("SELECT id FROM _vt.vdiff_tablet WHERE uuid=?", 1, true)
if len(qr.Rows) == 0 { return errors.New("vdiff UUID not present on this tablet; create first") }

if strings.Contains(err.Error(), "not found on tablet") {
    // create the vdiff or retarget the correct tablet
}

When it happens

Trigger: Calling vdiff resume (or action other than create) with a UUID that has no row in _vt.vdiff_tablet on the targeted tablet; targeting the wrong tablet alias.

Common situations: vdiff was created on a different tablet or already deleted; resuming before ever creating; cluster rebuilt/wiped losing _vt tables; passing a workflow-wide UUID to a tablet that never stored it.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• unable to %s vdiff for UUID %s as it was not found on tablet
• no vdiff found for UUID %s keyspace %s and workflow %s on ta
• no vdiff found for id %d on tablet %v
• no state found for vdiff table %s for vdiff_id %d on tablet
• VDiff not implemented in vtcombo

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