vitessio/vitess · error

Not a valid UUID: %s

Error message

Not a valid UUID: %s

What it means

TabletExecutor.SetUUIDList validates each provided migration UUID with schema.IsOnlineDDLUUID before accepting them. Any entry that is not a valid Online DDL UUID causes this error. It fires before the duplicate check, so the invalid UUID is the first one failing validation.

Source

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

	}
}

// SetDDLStrategy applies ddl_strategy from command line flags
func (exec *TabletExecutor) SetDDLStrategy(ddlStrategy string) error {
	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 {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Verify each entry is a full valid UUID as reported by vtctldclient GetSchemaMigrations
2. List existing migrations with vtctldclient GetSchemaMigrations --keyspace <ks> and copy the exact UUIDs
3. Check shell quoting/splitting so UUIDs are not truncated or corrupted before the call

Example fix

// before
exec.SetUUIDList([]string{"4b5c1e2a"}) // truncated
// after
exec.SetUUIDList([]string{"f7d29e6a1c3b4d5e8f9012345678abcd"})

for _, u := range uuids {
  if !schema.IsOnlineDDLUUID(u) {
    return fmt.Errorf("%q is not a valid Online DDL UUID", u)
  }
}

When it happens

Trigger: Calling SetUUIDList with a string that is not a valid UUID (e.g. empty string, a migration ID, a truncated or malformed UUID).

Common situations: Passing shard-targeted migration identifiers instead of UUIDs; copy/paste errors dropping characters; shell quoting issues mangling the UUID; using a human-readable migration label from --uuid-prefix flows.

Related errors

• UUID values must be unique
• Invalid UUID: %s, expected condensed 32 hexadecimals
• schema change failed, ExecuteResult: %v
• unknown schema migration strategy: '%v'
• unknown enum name for SchemaMigration_Status: %s

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