{"record":{"id":"8b19eee425771c72","repo":"vitessio/vitess","slug":"query-not-supported-by-vexec","errorCode":null,"errorMessage":"query not supported by vexec","messagePattern":"query not supported by vexec","errorType":"error_code","errorClass":"ErrUnsupportedQuery","httpStatus":null,"severity":"error","filePath":"go/vt/vtctl/workflow/vexec/vexec.go","lineNumber":63,"sourceCode":"\tVReplicationLogTableName = \"vreplication_log\"\n\t// VReplicationTableName is the unqualified name of the vreplication table\n\t// supported by vexec.\n\tVReplicationTableName = \"vreplication\"\n)\n\nvar ( // Topo lookup errors.\n\t// ErrNoShardPrimary occurs when a shard is found with no serving\n\t// primary.\n\tErrNoShardPrimary = errors.New(\"no primary found for shard\")\n\t// ErrNoShardsForKeyspace occurs when attempting to run a vexec on an empty\n\t// keyspace.\n\tErrNoShardsForKeyspace = errors.New(\"no shards found in keyspace\")\n)\n\nvar ( // Query parsing and planning errors.\n\t// ErrUnsupportedQuery occurs when attempting to run an unsupported query\n\t// through vexec.\n\tErrUnsupportedQuery = errors.New(\"query not supported by vexec\")\n\t// ErrUnsupportedTable occurs when attempting to run vexec on an unsupported\n\t// table. At the time of writing, this occurs when attempting to query any\n\t// table other than _vt.vreplication.\n\tErrUnsupportedTable = errors.New(\"table not supported by vexec\")\n)\n\n// VExec provides the main interface to planning and executing vexec queries\n// (normally, queries on tables in the `_vt` database). It currently supports\n// some limited vreplication queries; this set of supported behavior will expand\n// over time. It may be extended to support schema_migrations queries as well.\ntype VExec struct {\n\tts  *topo.Server\n\ttmc tmclient.TabletManagerClient\n\n\tkeyspace string\n\tworkflow string\n\n\t// (TODO:@ajm188) Consider renaming this field to \"targets\", and then","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtctl/workflow/vexec/vexec.go#L45-L81","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Restrict vexec usage to supported statements: simple SELECT/UPDATE/DELETE on _vt.vreplication with planner-supported WHERE clauses.","Simplify the query — drop unsupported clauses such as LIMIT/ORDER BY/JOIN and filter by a supported key.","Use vtctldclient workflow commands (WorkflowStart/WorkflowStop etc.) instead of raw vexec for vreplication lifecycle operations.","If the query genuinely needs support, open/patch the planner in go/vt/vtctl/workflow/vexec."],"exampleFix":"// before\nvexec.Run(ctx, ts, \"SELECT vr.* FROM _vt.vreplication vr JOIN _vt.copy_state cs ON vr.id=cs.vrepl_id\", \"commerce\")\n// after\nvexec.Run(ctx, ts, \"SELECT id, workflow, state FROM _vt.vreplication WHERE workflow='sales2commerce'\", \"commerce\")","handlingStrategy":"validation","validationCode":"allowed := map[sqlparser.StatementType]bool{sqlparser.StmtSelect: true, sqlparser.StmtUpdate: true, sqlparser.StmtDelete: true}\nst, _ := sqlparser.SplitStatementStatement(q)\nif !allowed[st] { return fmt.Errorf(\"vexec does not support %v\", st) }","typeGuard":null,"tryCatchPattern":"plan, err := vexec.PlanQuery(ctx, ts, keyspace, q)\nif err != nil {\n    if errors.Is(err, vexec.ErrUnsupportedQuery) {\n        // fall back to vtctldclient workflow commands or reject the request\n    }\n    return err\n}","preventionTips":["Keep vexec queries to the supported subset on _vt.vreplication.","Avoid LIMIT/ORDER BY/JOIN in vexec statements.","Prefer vtctldclient workflow commands for vreplication lifecycle ops."],"tags":["vexec","sql","planner","unsupported-query"],"backgroundTag":"unsupported-query-statement","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}