vitessio/vitess · error

--%s requires name=value

Error message

--%s requires name=value

What it means

SessionVariables() expects each --session-variable flag to be followed by exactly one token of the form name=value. This error is thrown when the flag appears at the end of the token list with no following token at all.

Source

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

	// 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
	}
	return variables, nil
}

// IsPostponeLaunch checks if strategy options include --postpone-launch
func (setting *DDLStrategySetting) IsPostponeLaunch() bool {
	return setting.hasFlag(postponeLaunchFlag)
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Provide the name=value token right after the flag: --session-variable name=value.
2. Quote values containing spaces so they split as one token.
3. Check the command/template that builds the strategy string for dropped empty values.

Example fix

// before
setting := schema.ParseDDLStrategy("online --session-variable")
// after
setting := schema.ParseDDLStrategy("online --session-variable wait_timeout=100")

if strings.HasSuffix(strings.TrimSpace(options), "--session-variable") {
    // append the name=value token
}

if _, err := setting.SessionVariables(); err != nil {
    return fmt.Errorf("bad DDL strategy options: %w", err)
}

When it happens

Trigger: A strategy string ending in the bare flag, e.g. "online --session-variable", or where the value got consumed as a separate flag token; detected when i+1 >= len(opts) after matching isFlag(opts[i], sessionVariableFlag).

Common situations: Value containing a space without quotes so shlex splits it away; trailing flag left by an empty variable in a template; flag appended last in generated commands with the value dropped by an empty-string filter.

Related errors

• invalid --%s value %q: expected name=value
• invalid DDL strategy options: %w
• stray %% at the end of pattern
• overflow
• too many .s

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