What causes "invalid DDL strategy options: %w" in vitessio/vitess?

Fix the quoting in the strategy options so shlex can split them (balance all quotes).

invalid DDL strategy options: %w

Error message

invalid DDL strategy options: %w

What it means

DDLStrategySetting.SessionVariables() tokenizes the strategy's Options string with shlex.Split; this error wraps a shell-lexing failure. It means the options text is unparseable, typically due to unbalanced or malformed quoting, and no session variables can be extracted.

Source

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

func (variable SessionVariable) SetStatement() (string, error) {
	if err := ValidateSessionVariable(variable); err != nil {
		return "", err
	}
	// A connection default or an earlier assignment may enable
	// NO_BACKSLASH_ESCAPES.
	// In that mode, encoding O'Reilly as 'O\'Reilly' closes the string after
	// the backslash; on a multi-statement DBA connection, a crafted suffix could
	// then be parsed as another statement. A hex literal is parsed safely
	// regardless of the active sql_mode.
	return fmt.Sprintf("set @@session.%s=X'%x'", variable.Name, variable.Value), nil
}

// SessionVariables returns the ordered assignments from repeatable
// --session-variable name=value options.
func (setting *DDLStrategySetting) SessionVariables() ([]SessionVariable, error) {
	opts, err := shlex.Split(setting.Options)
	if err != nil {
		return nil, fmt.Errorf("invalid DDL strategy options: %w", err)
	}
	var variables []SessionVariable
	for i := 0; i < len(opts); i++ {
		if !isFlag(opts[i], sessionVariableFlag) {
			continue
		}
		if i+1 >= len(opts) {
			return nil, fmt.Errorf("--%s requires name=value", sessionVariableFlag)
		}
		i++
		name, value, found := strings.Cut(opts[i], "=")
		if !found {
			return nil, fmt.Errorf("invalid --%s value %q: expected name=value", sessionVariableFlag, opts[i])
		}
		variables = append(variables, SessionVariable{Name: name, Value: value})
	}
	if err := ValidateSessionVariables(variables); err != nil {
		return nil, err

View on GitHub (pinned to 01a25a7d17)

Solutions

Fix the quoting in the strategy options so shlex can split them (balance all quotes).
Test the options string with shlex.Split directly to see the underlying parse error.
Simplify: avoid quotes in values or use escaped forms shlex accepts.

Example fix

// before
setting := schema.ParseDDLStrategy("online --session-variable foo='bar")
// after
setting := schema.ParseDDLStrategy("online --session-variable foo=bar")

Defensive patterns

Strategy: validation

Validate before calling

if _, err := shlex.Split(options); err != nil {
    // fix quoting before passing to ParseDDLStrategy
}

Try / catch

setting := schema.ParseDDLStrategy(strategyStr)
if setting.SessionVariables == nil { /* parse path surfaced the error */ }

Prevention

Quote values containing spaces or quotes; balance all quotes.
Test strategy strings through the exact shell layers that will run them.
Avoid embedding user text into strategy options unescaped.

When it happens

Trigger: A --ddl-strategy value whose trailing options contain unbalanced quotes, e.g. "online --session-variable foo='bar" (unterminated single quote), passed through ParseDDLStrategy.

Common situations: Quoting mangled by shell layers or CI YAML templating; values containing spaces or quotes pasted without escaping; differing quoting conventions between local shell and container exec.

Related errors

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