can only show a specific vdiff, please provide a valid UUID;

Error message

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

What it means

commandVDiff2 validates the argument to `VDiff -- ks.workflow show`. For the show action, only the special args `all` or `last` are allowed non-UUID, anything else must parse as a valid UUID. If uuid.Parse fails, this error is returned telling the user how to list all vdiffs instead.

Source

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

	var vdiffUUID uuid.UUID
	switch action {
	case vdiff.CreateAction:
		if actionArg != "" {
			vdiffUUID, err = uuid.Parse(actionArg)
		} 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)

View on GitHub (pinned to 01a25a7d17)

Solutions

Run `VDiff -- <keyspace>.<workflow> show all` to list valid vdiff UUIDs, then use the full UUID.
Use `show last` if you want the most recent vdiff instead of a specific one.
Verify the UUID is complete, unquoted-exact, and has no trailing whitespace.
Check the VDiff action/argument order matches the expected CLI form: VDiff -- <keyspace.workflow> show <uuid|all|last>.

Example fix

// before
VDiff -- commerce.move.tables show bd2f3e
// after
VDiff -- commerce.move.tables show all
VDiff -- commerce.move.tables show 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
const arg = "bd2f3e5a-1234-5678-9abc-def012345678"
if (!/^(all|last)$/.test(arg) && !uuidRe.test(arg.trim())) {
  throw new Error(`use 'show all' or a valid UUID, got: ${arg}`)
}

Type guard

function isVDiffShowArg(s) {
  return s === "all" || s === "last" || /^[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(`-- commerce.move.tables show ${arg}`)
} catch (e) {
  if (String(e).includes("provide a valid UUID")) {
    console.error("Listing vdiffs instead:")
    runVDiff("-- commerce.move.tables show all")
  } else throw e
}

Prevention

Always run `show all` first and copy a UUID verbatim from the output.
Use `show last` instead of hunting for a UUID when you want the latest vdiff.
Quote arguments in shell scripts to avoid token splitting.

When it happens

Trigger: Running `VDiff -- <keyspace>.<workflow> show <arg>` where <arg> is neither `all`/`last` nor a parseable UUID string (e.g. a truncated UUID, a name/label, a typo, or an empty extra argument).

Common situations: Developers passing a human-friendly label or partial UUID to `show`; shell quoting splitting the argument so an empty/garbage token reaches the parser; copying a UUID with surrounding whitespace or braces.

Related errors

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