unable to %s vdiff for UUID %s as it was not found on tablet

Error message

unable to %s vdiff for UUID %s as it was not found on tablet %v (%w)

What it means

After determining the vdiff record id, Vitess re-fetches the full vdiff row by id (getVDiffByID); if the row is gone (nil) it reports the action cannot proceed because the record vanished, wrapping any error from the fetch. This is a race/consistency guard between the first lookup and the by-id fetch.

Source

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

			rowsAffected, err := execResume(sqlStartVDiff)
			if err != nil {
				return err
			}
			if rowsAffected == 0 {
				return fmt.Errorf("no completed or stopped vdiff found for UUID %s on tablet %s",
					req.VdiffUuid, topoproto.TabletAliasString(vde.thisTablet.Alias))
			}
		}
	}

	resp.VdiffUuid = req.VdiffUuid
	qr, err = vde.getVDiffByID(ctx, dbClient, resp.Id)
	if err != nil {
		return err
	}
	vdiffRecord := qr.Named().Row()
	if vdiffRecord == nil {
		return fmt.Errorf("unable to %s vdiff for UUID %s as it was not found on tablet %v (%w)",
			action, req.VdiffUuid, topoproto.TabletAliasString(vde.thisTablet.Alias), err)
	}
	if action == ResumeAction {
		// Use the existing options from the vdiff record.
		options = optionsZeroVal
		err = protojson.Unmarshal(vdiffRecord.AsBytes("options", []byte("{}")), options)
		if err != nil {
			return err
		}
	}

	vde.mu.Lock()
	defer vde.mu.Unlock()
	if err := vde.addController(vdiffRecord, options); err != nil {
		return err
	}

	return nil

View on GitHub (pinned to 01a25a7d17)

Solutions

Re-run the vdiff action after confirming the record's existence with vdiff show
Avoid running concurrent vdiff delete and create/resume for the same UUID
Check tablet logs for the wrapped error from getVDiffByID
Re-create the vdiff if it was intentionally deleted

Defensive patterns

Strategy: retry

Validate before calling

// re-check existence immediately before acting:
qr, err := dbClient.ExecuteFetch("SELECT id FROM _vt.vdiff_tablet WHERE uuid=?", 1, true)
if err != nil || len(qr.Rows) == 0 { return errors.New("vdiff missing; aborting") }

Try / catch

if strings.Contains(err.Error(), "as it was not found on tablet") {
    // record vanished mid-operation; verify with show and retry or re-create
}

Prevention

Serialize vdiff operations per UUID (no concurrent delete + resume)
Use a single operator/tool to drive vdiff lifecycles
Re-run show after the error to confirm the record's fate

When it happens

Trigger: Concurrent deletion of the vdiff record (or an internal fetch error producing no row) between the initial UUID lookup and getVDiffByID inside handleCreateResumeAction; also fires when the fetch returned err and a nil row.

Common situations: Another operator or a cleanup job deleted the vdiff mid-operation; concurrent vdiff delete while resuming; replica-local _vt table changes applied between the two queries.

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

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