What causes "unable to create vdiff for UUID %s on tablet %s (%w)" in vitessio/vitess?

Check the wrapped error (%w) in the message for the root MySQL cause

unable to create vdiff for UUID %s on tablet %s (%w)

Error message

unable to create vdiff for UUID %s on tablet %s (%w)

What it means

After executing the INSERT that creates the vdiff record, Vitess checks qr.InsertID; if it is 0 the insert did not actually create a row, so it reports that vdiff creation failed, wrapping the underlying error. This guards against inserts that silently affected no rows.

Source

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

			state = StoppedState
		}
		query, err := sqlparser.ParseAndBind(sqlNewVDiff,
			sqltypes.StringBindVariable(req.Keyspace),
			sqltypes.StringBindVariable(req.Workflow),
			sqltypes.StringBindVariable(string(state)),
			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 {

View on GitHub (pinned to 01a25a7d17)

Solutions

Check the wrapped error (%w) in the message for the root MySQL cause
Verify _vt.vdiff_tablet schema is current (run online DDL / schema migration checks) on the tablet
Re-run the vdiff create after fixing the underlying error
Ensure the target tablet is healthy (serving, not in a failed migration state)

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure _vt.vdiff_tablet exists and is writable on the tablet before creating vdiffs

Try / catch

var insertErr error
if strings.Contains(err.Error(), "unable to create vdiff") {
    insertErr = err // inspect wrapped %w cause for the MySQL-level failure
    log.Errorf("vdiff create failed: %v", insertErr)
}

Prevention

Keep tablet _vt schema migrations current
Ensure target tablets are healthy and serving before vdiff create
Surface and log the wrapped error for root cause

When it happens

Trigger: The INSERT into _vt.vdiff_tablet returns InsertID == 0 — e.g. the query executed but inserted nothing due to table schema issues, or the wrapped err context (like a MySQL error surfaced as 0 rows) — inside handleCreateResumeAction on a vdiff create.

Common situations: _corrupt or mismatched _vt.vdiff_tablet schema on the tablet; MySQL-level errors during the insert; replica tablets whose local schema lags behind the vitess metadata migration.

Related errors

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