What causes "UUID values must be unique" in vitessio/vitess?

Deduplicate the UUID slice before passing it to SetUUIDList

UUID values must be unique

Error message

UUID values must be unique

What it means

SetUUIDList validates the UUID list provided to a TabletExecutor. Each UUID must be a valid Online DDL UUID and all values must be distinct; it returns this error when the deduplication map's size is smaller than the input slice, i.e. duplicates were supplied.

Source

Thrown at go/vt/schemamanager/tablet_executor.go:99

	ddlStrategySetting, err := schema.ParseDDLStrategy(ddlStrategy)
	if err != nil {
		return err
	}
	exec.ddlStrategySetting = ddlStrategySetting
	return nil
}

// SetUUIDList sets a (possibly empty) list of provided UUIDs for schema migrations
func (exec *TabletExecutor) SetUUIDList(uuids []string) error {
	uuidsMap := map[string]bool{}
	for _, uuid := range uuids {
		if !schema.IsOnlineDDLUUID(uuid) {
			return fmt.Errorf("Not a valid UUID: %s", uuid)
		}
		uuidsMap[uuid] = true
	}
	if len(uuidsMap) != len(uuids) {
		return errors.New("UUID values must be unique")
	}
	exec.uuids = uuids
	return nil
}

// hasProvidedUUIDs returns true when UUIDs were provided
func (exec *TabletExecutor) hasProvidedUUIDs() bool {
	return len(exec.uuids) != 0
}

// Open opens a connection to the primary for every shard.
func (exec *TabletExecutor) Open(ctx context.Context, keyspace string) error {
	if !exec.isClosed {
		return nil
	}
	exec.keyspace = keyspace
	shards, err := exec.ts.FindAllShardsInKeyspace(ctx, keyspace, nil)
	if err != nil {

View on GitHub (pinned to 01a25a7d17)

Solutions

Deduplicate the UUID slice before passing it to SetUUIDList
Fix the source configuration/script so each migration UUID appears once
Validate UUIDs with schema.IsOnlineDDLUUID and a uniqueness check before submission

Example fix

// before
uuids := []string{"a1b2...", "a1b2..."}
exec.SetUUIDList(ctx, uuids) // UUID values must be unique
// after
seen := map[string]bool{}
var unique []string
for _, u := range uuids {
    if !seen[u] {
        seen[u] = true
        unique = append(unique, u)
    }
}
exec.SetUUIDList(ctx, unique)

Defensive patterns

Strategy: validation

Validate before calling

func uniqueUUIDs(uuids []string) bool {
	seen := map[string]bool{}
	for _, u := range uuids {
		if seen[u] { return false }
		seen[u] = true
	}
	return true
}

Prevention

Deduplicate UUID lists before executor setup
Generate UUIDs programmatically instead of hand-copying
Validate with schema.IsOnlineDDLUUID and uniqueness checks upstream

When it happens

Trigger: Calling SetUUIDList with a slice containing the same Online DDL UUID more than once.

Common situations: Batching migration UUIDs from configuration or scripts that accidentally repeat an entry; copy-paste errors in explicit-UUID migration execution.

Related errors

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