vitessio/vitess · error

error parsing vschema statement `%s`: %v

Error message

error parsing vschema statement `%s`: %v

What it means

The RebuildKeyspace/VSchema command failed to parse the user-supplied vschema SQL statement with the SQL parser. The raw statement is embedded in the error along with the parser error. This is a client-side parse validation before any topo mutation happens.

Source

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

		return errors.New("only one of the --sql, --sql_file, --vschema, or --vschema_file flags may be specified when calling the ApplyVSchema command")
	}

	if !sqlMode && !jsonMode {
		return errors.New("one of the --sql, --sql_file, --vschema, or --vschema_file flags must be specified when calling the ApplyVSchema command")
	}

	if sqlMode {
		if *sqlFile != "" {
			sqlBytes, err := os.ReadFile(*sqlFile)
			if err != nil {
				return err
			}
			*sql = string(sqlBytes)
		}

		stmt, err := wr.SQLParser().Parse(*sql)
		if err != nil {
			return fmt.Errorf("error parsing vschema statement `%s`: %v", *sql, err)
		}
		ddl, ok := stmt.(*sqlparser.AlterVschema)
		if !ok {
			return fmt.Errorf("error parsing vschema statement `%s`: not a ddl statement", *sql)
		}

		ksvs, err = topotools.ApplyVSchemaDDL(ctx, keyspace, wr.TopoServer(), ddl)
		if err != nil {
			return err
		}
	} else {
		// json mode
		var schema []byte
		if *vschemaFile != "" {
			var err error
			schema, err = os.ReadFile(*vschemaFile)
			if err != nil {
				return err

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Validate the vschema statement syntax locally with a SQL parser or `vtctldclient` dry run before applying
2. Check the embedded `%v` parser error for the exact token/position that failed
3. If embedding JSON, ensure it is properly quoted/escaped in the shell or file

Example fix

// before
sql := `ALTER VSCHEMA ADD TABLE test`  // missing vindex spec, parse fails
// after
sql := `ALTER VSCHEMA ADD TABLE test vindex hash`

stmt, err := sqlparser.Parse(sql)
if err != nil {
	return fmt.Errorf("invalid vschema statement %q: %v", sql, err)
}
if _, ok := stmt.(*sqlparser.AlterVschema); !ok {
	return fmt.Errorf("must be ALTER VSCHEMA statement")
}

func isAlterVschema(stmt sqlparser.Statement) bool {
	_, ok := stmt.(*sqlparser.AlterVschema)
	return ok
}

if err := applyVSchema(sql); err != nil {
	if strings.Contains(err.Error(), "error parsing vschema statement") {
		return fmt.Errorf("check vschema syntax: %w", err)
	}
	return err
}

When it happens

Trigger: Running `vtctldclient RebuildVSchemaGraph`/ApplyVSchema with an `*sql` string that is not valid vschema DDL syntax (e.g. malformed `ALTER VSCHEMA ADD TABLE ...`).

Common situations: Typo in vindex definition JSON, missing semicolons/quotes, passing a plain DDL statement instead of an AlterVschema, JSON with special characters not escaped in shell.

Related errors

• error parsing vschema statement `%s`: not a ddl statement
• table expression is complex
• Error generating OnlineDDL query: %+v
• keyspace(%s) doesn't exist, check if the keyspace is initial
• missing keyspace %q in cell %q

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