can only %s a specific vdiff, please provide a valid UUID; v

Error message

can only %s a specific vdiff, please provide a valid UUID; view all with: VDiff -- %s.%s show all

What it means

For the `stop` and `resume` VDiff actions, commandVDiff2 requires the argument to be a specific, valid vdiff UUID. If uuid.Parse fails on the actionArg, it returns this formatted error (the action name is interpolated) pointing the user at `show all` to find UUIDs.

Source

Thrown at go/vt/vtctl/vdiff2.go:155

		} else {
			vdiffUUID, err = uuid.NewUUID()
		}
		if err != nil {
			return fmt.Errorf("%v, please provide a valid UUID", err)
		}
	case vdiff.ShowAction:
		switch actionArg {
		case vdiff.AllActionArg, vdiff.LastActionArg:
		default:
			vdiffUUID, err = uuid.Parse(actionArg)
			if err != nil {
				return fmt.Errorf("can only show a specific vdiff, please provide a valid UUID; view all with: VDiff -- %s.%s show all", keyspace, workflowName)
			}
		}
	case vdiff.StopAction, vdiff.ResumeAction:
		vdiffUUID, err = uuid.Parse(actionArg)
		if err != nil {
			return fmt.Errorf("can only %s a specific vdiff, please provide a valid UUID; view all with: VDiff -- %s.%s show all", action, keyspace, workflowName)
		}
	case vdiff.DeleteAction:
		switch actionArg {
		case vdiff.AllActionArg:
		default:
			vdiffUUID, err = uuid.Parse(actionArg)
			if err != nil {
				return fmt.Errorf("can only delete a specific vdiff, please provide a valid UUID; view all with: VDiff -- %s.%s show all", keyspace, workflowName)
			}
		}
	default:
		return fmt.Errorf("invalid action '%s'; %s", action, usage)
	}

	output, err := wr.VDiff2(ctx, keyspace, workflowName, action, actionArg, vdiffUUID.String(), options)
	if err != nil {
		log.Error(fmt.Sprintf("vdiff2 returning with error: %v", err))
		return err

View on GitHub (pinned to 01a25a7d17)

Solutions

Get the exact UUID with `VDiff -- <keyspace>.<workflow> show all`.
Pass the full valid UUID to the stop/resume action.
Do not use `all`/`last` with stop or resume — only `show` supports them.
Re-check shell quoting so the UUID arrives as a single argument.

Example fix

// before
VDiff -- commerce.move.tables stop last
// after
VDiff -- commerce.move.tables show all
VDiff -- commerce.move.tables stop bd2f3e5a-1234-5678-9abc-def012345678

Defensive patterns

Strategy: validation

Validate before calling

const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
if (!uuidRe.test(arg.trim())) {
  throw new Error(`stop/resume require a full vdiff UUID, got: ${arg}`)
}

Type guard

function isVDiffUUID(s) {
  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s)
}

Try / catch

try {
  runVDiff(`-- ${ks}.${wf} stop ${uuid}`)
} catch (e) {
  if (String(e).includes("provide a valid UUID")) {
    const list = runVDiff(`-- ${ks}.${wf} show all`)
    console.error(`Unknown UUID ${uuid}; available: ${list}`)
  } else throw e
}

Prevention

Remember stop/resume only accept exact UUIDs — never `all` or `last`.
Fetch the UUID programmatically from `show all` output before stopping/resuming.
Trim copied UUIDs to strip whitespace and shell artifacts.

When it happens

Trigger: Running `VDiff -- <keyspace>.<workflow> stop <arg>` or `resume <arg>` where <arg> is not a valid UUID — e.g. passing `all`, `last`, a table name, or a malformed UUID.

Common situations: Assuming stop/resume accept `all`/`last` like the show action does (they don't); using a vdiff name from another tool; truncated UUIDs pasted from terminal output.

Related errors

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