What causes "unknown schema migration strategy: '%v'" in vitessio/vitess?

Use an exact valid strategy name; check proto/vtctldata.proto SchemaMigration.Strategy for the accepted values.

unknown schema migration strategy: '%v'

Error message

unknown schema migration strategy: '%v'

What it means

ParseSchemaMigrationStrategy converts a user-supplied strategy name (e.g. from an online DDL migration request) into the vtctldatapb.SchemaMigration_Strategy enum by upper-casing and looking it up in the generated enum value map. If the name does not match any known strategy, this error is returned. It is a pure input-validation error before any migration is started.

Source

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

	sd, err := tmc.GetSchema(ctx, ti.Tablet, request)
	if err != nil {
		return nil, vterrors.Wrapf(err, "GetSchema(%v, %v) failed", ti.Tablet, request)
	}

	return sd, nil
}

// ParseSchemaMigrationStrategy parses the given strategy into the underlying enum type.
func ParseSchemaMigrationStrategy(name string) (vtctldatapb.SchemaMigration_Strategy, error) {
	if name == "" {
		// backward compatiblity and to handle unspecified values
		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.

View on GitHub (pinned to 01a25a7d17)

Solutions

Use an exact valid strategy name; check proto/vtctldata.proto SchemaMigration.Strategy for the accepted values.
Trim whitespace and retry — lookup is exact after ToUpper.
If the value came from an older/newer Vitess version, align client tooling with the current enum names.
List valid values programmatically: keys of vtctldatapb.SchemaMigration_Strategy_value.

Example fix

// before
strategy, err := schematools.ParseSchemaMigrationStrategy("gh-ost") // unknown
// after
strategy, err := schematools.ParseSchemaMigrationStrategy("online") // or another valid enum name

Defensive patterns

Strategy: validation

Validate before calling

validStrategies := map[string]bool{"direct": true, "online": true}
if !validStrategies[strings.ToLower(strings.TrimSpace(strategyName))] {
  return fmt.Errorf("strategy %q not in %v", strategyName, validStrategies)
}

Type guard

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

Try / catch

strategy, err := schematools.ParseSchemaMigrationStrategy(name)
if err != nil {
  return fmt.Errorf("bad -strategy value %q: %w (valid: direct, online)", name, err)
}

Prevention

Reference the generated enum names in proto/vtctldata.proto instead of hardcoding strings.
Trim and upper-case user input before parsing.
Pin client automation to the Vitess version whose enum names it targets.
Surface the list of valid values in CLI help/errors.

When it happens

Trigger: Calling ParseSchemaMigrationStrategy with a string other than the valid strategies (e.g. "mysql"/"maria" expected values like "DIRECT"/"Online" depending on the enum): typically bad -strategy flag or bad row value when converting a row to SchemaMigration.

Common situations: Typo in an online DDL strategy flag (`-strategy`); strategy supplied by an automation script using a value from a different Vitess version; case/format issues like trailing whitespace or hyphen vs underscore.

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

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