vitessio/vitess · error

unknown enum name for SchemaMigration_Status: %s

Error message

unknown enum name for SchemaMigration_Status: %s

What it means

ParseSchemaMigrationStatus converts a status name string into the vtctldatapb.SchemaMigration_Status enum via an exact upper-case map lookup. When the provided name is not a defined status (e.g. not "running", "complete", "failed", "cancelled", "queued"), this error is returned. It is input validation and does not indicate any migration actually ran.

Source

Thrown at go/vt/vtctl/schematools/schematools.go:72

		return vtctldatapb.SchemaMigration_DIRECT, nil
	}

	upperName := strings.ToUpper(name)
	strategy, ok := vtctldatapb.SchemaMigration_Strategy_value[upperName]
	if !ok {
		return 0, fmt.Errorf("unknown schema migration strategy: '%v'", name)
	}

	return vtctldatapb.SchemaMigration_Strategy(strategy), nil
}

// ParseSchemaMigrationStatus parses the given status into the underlying enum type.
func ParseSchemaMigrationStatus(name string) (vtctldatapb.SchemaMigration_Status, error) {
	key := strings.ToUpper(name)

	val, ok := vtctldatapb.SchemaMigration_Status_value[key]
	if !ok {
		return 0, fmt.Errorf("unknown enum name for SchemaMigration_Status: %s", name)
	}

	return vtctldatapb.SchemaMigration_Status(val), nil
}

// SchemaMigrationStrategyName returns the text-based form of the strategy.
func SchemaMigrationStrategyName(strategy vtctldatapb.SchemaMigration_Strategy) string {
	name, ok := vtctldatapb.SchemaMigration_Strategy_name[int32(strategy)]
	if !ok {
		return "unknown"
	}
	return strings.ToLower(name)
}

// SchemaMigrationStatusName returns the text-based form of the status.
func SchemaMigrationStatusName(status vtctldatapb.SchemaMigration_Status) string {
	return strings.ToLower(vtctldatapb.SchemaMigration_Status_name[int32(status)])
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Use an exact valid status name per vtctldatapb.SchemaMigration_Status in proto/vtctldata.proto.
2. Trim/normalize the input string before parsing.
3. If migrating stored data, map legacy status names to current enum names before calling the parser.
4. Enumerate valid keys via vtctldatapb.SchemaMigration_Status_value to confirm spelling.

Example fix

// before
status, err := schematools.ParseSchemaMigrationStatus("succes") // typo
// after
status, err := schematools.ParseSchemaMigrationStatus("complete")

validStatuses := map[string]bool{"queued": true, "running": true, "complete": true, "failed": true, "cancelled": true}
if !validStatuses[strings.ToLower(strings.TrimSpace(statusName))] {
  return fmt.Errorf("status %q not recognized", statusName)
}

func isValidMigrationStatus(name string) bool {
  _, ok := vtctldatapb.SchemaMigration_Status_value[strings.ToUpper(strings.TrimSpace(name))]
  return ok
}

status, err := schematools.ParseSchemaMigrationStatus(name)
if err != nil {
  return fmt.Errorf("bad -status filter %q: %w (see SchemaMigration_Status enum)", name, err)
}

When it happens

Trigger: commandOnlineDDLShow with a `-status` filter value that is not a defined enum name, or rowToSchemaMigration reading a status string from persistence that no longer matches current enum names.

Common situations: Typo in `vtctldclient OnlineDDL show -status`; status string from an older schema/migration table written by a different Vitess version; lowercase/mixed formatting with stray spaces defeating the exact-match lookup.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unknown schema migration strategy: '%v'
• Not a valid UUID: %s
• unknown keyspace type %v
• ErrPartSize
• BeforeSchema differs

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