What causes "Error generating OnlineDDL query: %+v" in vitessio/vitess?

Check the wrapped inner error (%+v) for the parser failure detail

Error generating OnlineDDL query: %+v

Error message

Error generating OnlineDDL query: %+v

What it means

When the OnlineDDL command is recognized, vtctl delegates SQL generation to generateOnlineDDLQuery. If that helper fails (e.g. sqlparser.ParseAndBind cannot build the ALTER VITESS_MIGRATION statement for the given UUID), the error is wrapped with this message. It indicates the command string was valid but constructing the query failed.

Source

Thrown at go/vt/vtctl/vtctl.go:3097

		applySchemaQuery, err = generateOnlineDDLQuery(command, arg, false)
	case
		"launch",
		"launch-all",
		"complete",
		"complete-all",
		"cancel",
		"cancel-all",
		"throttle",
		"throttle-all",
		"unthrottle",
		"unthrottle-all":
		// Support 'ALL' argument
		applySchemaQuery, err = generateOnlineDDLQuery(command, arg, true)
	default:
		return fmt.Errorf("Unknown OnlineDDL command: %s", command)
	}
	if err != nil {
		return fmt.Errorf("Error generating OnlineDDL query: %+v", err)
	}

	if applySchemaQuery != "" {
		log.Info("Calling ApplySchema on VtctldServer")

		resp, err := wr.VtctldServer().ApplySchema(ctx, &vtctldatapb.ApplySchemaRequest{
			Keyspace:            keyspace,
			Sql:                 []string{applySchemaQuery},
			WaitReplicasTimeout: protoutil.DurationToProto(grpcvtctldserver.DefaultWaitReplicasTimeout),
		})
		if err != nil {
			return err
		}
		loggerWriter{wr.Logger()}.Printf("resp: %v\n", resp)
	} else {
		// This is a SELECT. We run this on all PRIMARY tablets of this keyspace, and return the combined result
		resp, err := wr.VtctldServer().GetTablets(ctx, &vtctldatapb.GetTabletsRequest{
			Cells:      nil,

View on GitHub (pinned to 01a25a7d17)

Solutions

Check the wrapped inner error (%+v) for the parser failure detail
Verify the migration UUID format (underscores, no spaces/quotes) using `workflow show` to list valid UUIDs
Quote the argument properly in the shell and retry

Example fix

// before
vtctldclient workflow complete "82fa7e00 f39e 11eb ..."  # spaces break binding
// after
vtctldclient workflow complete 82fa7e00_f39e_11eb_a1b2_0e44e0b34e9e

Defensive patterns

Strategy: try-catch

Validate before calling

// validate UUID shape first
ok := regexp.MustCompile(`^[0-9a-f_]+$`).MatchString(uuid)
if !ok { fail("malformed migration UUID") }

Try / catch

err := runOnlineDDL(command, uuid)
if err != nil && strings.HasPrefix(err.Error(), "Error generating OnlineDDL query") {
  // inspect wrapped cause, fix the UUID/argument and retry
}

Prevention

Copy UUIDs verbatim from `workflow show` output
Quote arguments in shell to avoid splitting/mangling
Keep UUID format (underscore separators) intact

When it happens

Trigger: A UUID argument that breaks SQL binding (empty after normalization, embedded quotes, invalid characters); generateOnlineDDLQuery returning an error for an unusual command/arg combination.

Common situations: Passing a malformed migration UUID (wrong separators, truncated); shell mangling of the argument; internal parser mismatch after version upgrades.

Related errors

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