vitessio/vitess · error

%v, please provide a valid UUID

Error message

%v, please provide a valid UUID

What it means

For VDiff create/show actions, the optional third argument may be a UUID identifying a prior diff run. When it is supplied, commandVDiff2 parses it with uuid.Parse; a malformed UUID returns '%v, please provide a valid UUID'.

Source

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

		},
		ReportOptions: &tabletmanagerdatapb.VDiffReportOptions{
			OnlyPks:       *onlyPks,
			DebugQuery:    *debugQuery,
			Format:        format,
			MaxSampleRows: 10,
		},
	}

	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:

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Get a valid UUID from `VDiff -- ks.wf show all` output and pass it verbatim.
2. For show, use the keywords `all` or `last` instead of a partial UUID.
3. Check for shell mangling — quote the UUID argument.
4. If you meant to start a new diff, omit the third argument entirely; create generates a fresh UUID via uuid.NewUUID().

Example fix

// before
VDiff -- commerce.sell show 6ba7b810-9dad-11d1-80b4  # truncated
// after
VDiff -- commerce.sell show 6ba7b810-9dad-11d1-80b4-00c04fd430c8

if _, err := uuid.Parse(candidate); err != nil {
    return fmt.Errorf("%q is not a valid UUID", candidate)
}

func isUUID(s string) bool { _, err := uuid.Parse(s); return err == nil }

if err := runVDiff(args); err != nil {
    if strings.Contains(err.Error(), "please provide a valid UUID") {
        out, _ := runVDiff([]string{"ks.wf", "show", "all"})
        log.Warn("resolve UUID from full listing", slog.String("listing", out))
    }
}

When it happens

Trigger: `VDiff -- ks.wf show <text>` or `create <text>` where the third argument is not a canonical UUID (wrong length, missing hyphens, non-hex characters), so uuid.Parse fails and the wrapped error is returned.

Common situations: Truncating a UUID when copying from logs; passing a friendly name or shard key where a UUID is expected; passing 'all'/'last' to `create` (those keywords are only accepted for `show`); quoting issues stripping characters in the shell.

Related errors

• usage: VDiff -- <keyspace>.<workflow> %s [%s|<UUID>]
• invalid action '%s'; %s
• invalid --limit value (%d), maximum number of rows to compar
• can only show a specific vdiff, please provide a valid UUID;
• can only %s a specific vdiff, please provide a valid UUID; v

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