vitessio/vitess · error

Unknown online DDL strategy: '%v'

Error message

Unknown online DDL strategy: '%v'

What it means

ParseDDLStrategy parses the value of the @@ddl_strategy session variable. If the strategy token (the part before any '@' parameters) is not one of vitess, online, mysql, direct (or empty), parsing fails with this error listing the unknown value.

Source

Thrown at go/vt/schema/ddl_strategy.go:129

	}
}

// ParseDDLStrategy parses and validates the value of @@ddl_strategy or -ddl_strategy variables
func ParseDDLStrategy(strategyVariable string) (*DDLStrategySetting, error) {
	setting := &DDLStrategySetting{}
	strategyName := strategyVariable
	if submatch := strategyParserRegexp.FindStringSubmatch(strategyVariable); len(submatch) > 0 {
		strategyName = submatch[1]
		setting.Options = submatch[2]
	}

	switch strategy := DDLStrategy(strategyName); strategy {
	case "": // backward compatiblity and to handle unspecified values
		setting.Strategy = DDLStrategyDirect
	case DDLStrategyVitess, DDLStrategyOnline, DDLStrategyMySQL, DDLStrategyDirect:
		setting.Strategy = strategy
	default:
		return nil, fmt.Errorf("Unknown online DDL strategy: '%v'", strategy)
	}
	if _, err := setting.CutOverThreshold(); err != nil {
		return nil, err
	}
	if _, err := setting.RetainArtifactsDuration(); err != nil {
		return nil, err
	}
	if _, err := setting.SessionVariables(); err != nil {
		return nil, err
	}
	cutoverAfter, err := setting.ForceCutOverAfter()
	if err != nil {
		return nil, err
	}
	switch setting.Strategy {
	case DDLStrategyVitess, DDLStrategyOnline:
	default:
		if cutoverAfter != 0 {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Set ddl_strategy to a supported value: '', 'vitess', 'online', 'mysql', or 'direct' (e.g. SET @@ddl_strategy='vitess').
2. Fix the typo in the strategy name; use 'online' or 'vitess' for online schema changes.
3. Check Vitess docs for the current list of strategies; older strategy names (gh-ost, pt-osc) were removed.
4. Use vtctldclient or the app's allowed-strategy validation before issuing the SET statement.

Example fix

// before
SET @@ddl_strategy='gh-ost';
// after
SET @@ddl_strategy='vitess';

valid := map[string]bool{"": true, "vitess": true, "online": true, "mysql": true, "direct": true}
if !valid[strings.ToLower(strategy)] { return fmt.Errorf("unknown ddl strategy %q", strategy) }

func isKnownStrategy(s string) bool {
  switch schema.DDLStrategy(s) {
  case "", schema.DDLStrategyVitess, schema.DDLStrategyOnline, schema.DDLStrategyMySQL, schema.DDLStrategyDirect:
    return true
  }
  return false
}

setting, err := schema.ParseDDLStrategy(strategyName)
if err != nil {
  return fmt.Errorf("bad ddl_strategy %q: %w", strategyName, err)
}

When it happens

Trigger: Executing SET @@ddl_strategy='gh-ost' (or any misspelled/unrecognized strategy), or calling schema.ParseDDLStrategy programmatically with a bad strategyName.

Common situations: Typo in the strategy name; copied a gh-ost/pt-osc style value from another system; older clients passing deprecated values after upgrade; tools setting ddl_strategy via connection state.

Related errors

• session variable %q is not allowed
• duplicate session variable name: %q
• BeforeSchema differs
• AfterSchema differs
• --force-cut-over-after is only valid in 'vitess' strategy. F

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