vitessio/vitess · error · ErrUnsupportedQuery

query not supported by vexec

Error message

query not supported by vexec

What it means

ErrUnsupportedQuery is returned by vexec's query planner (PlanQuery, planDelete, planUpdate) when the submitted statement is outside the small set of queries vexec knows how to plan. vexec only supports a limited subset of statements on _vt.vreplication; anything else (joins, selects with unsupported clauses, other statement types) is rejected with this sentinel error.

Source

Thrown at go/vt/vtctl/workflow/vexec/vexec.go:63

	VReplicationLogTableName = "vreplication_log"
	// VReplicationTableName is the unqualified name of the vreplication table
	// supported by vexec.
	VReplicationTableName = "vreplication"
)

var ( // Topo lookup errors.
	// ErrNoShardPrimary occurs when a shard is found with no serving
	// primary.
	ErrNoShardPrimary = errors.New("no primary found for shard")
	// ErrNoShardsForKeyspace occurs when attempting to run a vexec on an empty
	// keyspace.
	ErrNoShardsForKeyspace = errors.New("no shards found in keyspace")
)

var ( // Query parsing and planning errors.
	// ErrUnsupportedQuery occurs when attempting to run an unsupported query
	// through vexec.
	ErrUnsupportedQuery = errors.New("query not supported by vexec")
	// ErrUnsupportedTable occurs when attempting to run vexec on an unsupported
	// table. At the time of writing, this occurs when attempting to query any
	// table other than _vt.vreplication.
	ErrUnsupportedTable = errors.New("table not supported by vexec")
)

// VExec provides the main interface to planning and executing vexec queries
// (normally, queries on tables in the `_vt` database). It currently supports
// some limited vreplication queries; this set of supported behavior will expand
// over time. It may be extended to support schema_migrations queries as well.
type VExec struct {
	ts  *topo.Server
	tmc tmclient.TabletManagerClient

	keyspace string
	workflow string

	// (TODO:@ajm188) Consider renaming this field to "targets", and then

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Restrict vexec usage to supported statements: simple SELECT/UPDATE/DELETE on _vt.vreplication with planner-supported WHERE clauses.
2. Simplify the query — drop unsupported clauses such as LIMIT/ORDER BY/JOIN and filter by a supported key.
3. Use vtctldclient workflow commands (WorkflowStart/WorkflowStop etc.) instead of raw vexec for vreplication lifecycle operations.
4. If the query genuinely needs support, open/patch the planner in go/vt/vtctl/workflow/vexec.

Example fix

// before
vexec.Run(ctx, ts, "SELECT vr.* FROM _vt.vreplication vr JOIN _vt.copy_state cs ON vr.id=cs.vrepl_id", "commerce")
// after
vexec.Run(ctx, ts, "SELECT id, workflow, state FROM _vt.vreplication WHERE workflow='sales2commerce'", "commerce")

allowed := map[sqlparser.StatementType]bool{sqlparser.StmtSelect: true, sqlparser.StmtUpdate: true, sqlparser.StmtDelete: true}
st, _ := sqlparser.SplitStatementStatement(q)
if !allowed[st] { return fmt.Errorf("vexec does not support %v", st) }

plan, err := vexec.PlanQuery(ctx, ts, keyspace, q)
if err != nil {
    if errors.Is(err, vexec.ErrUnsupportedQuery) {
        // fall back to vtctldclient workflow commands or reject the request
    }
    return err
}

When it happens

Trigger: Running a vexec query whose AST the planner does not handle — e.g. a SELECT, JOIN, INSERT, DDL, or an UPDATE/DELETE on _vt.vreplication with clauses (LIMIT, ORDER BY, complex WHERE) the planner's planUpdate/planDelete cannot translate to per-shard plans. Returned from PlanQuery and covered by TestVReplicationQueryPlanner_PlanQuery.

Common situations: Trying to run arbitrary SQL through VExec assuming it is a general-purpose query engine; using a WHERE clause or query shape not yet implemented; querying tables other than _vt.vreplication (that produces ErrUnsupportedTable instead).

Related errors

• ErrUnsupportedQuery
• Query must match one of these templates: %s
• query not supported by vexec: %s
• VT12001
• --batch-size only allowed when all queries are CREATE TABLE|

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