vitessio/vitess · error

query not supported by vexec: %s

Error message

query not supported by vexec: %s

What it means

buildInsertPlan only supports INSERT when the planner has insertTemplates configured for the target table; without a template there is no validated rewrite of the INSERT for sharded execution, so vexec refuses the query outright.

Source

Thrown at go/vt/wrangler/vexec_plan.go:319

	del.Where = vx.addDefaultWheres(planner, del.Where)

	buf := sqlparser.NewTrackedBuffer(nil)
	buf.Myprintf("%v", del)

	return &vexecPlan{
		opcode:      deleteQuery,
		parsedQuery: buf.ParsedQuery(),
	}, nil
}

// buildInsertPlan builds a plan for a INSERT query
func (vx *vexec) buildInsertPlan(ctx context.Context, planner vexecPlanner, ins *sqlparser.Insert) (*vexecPlan, error) {
	plannerParams := planner.params()
	templates := plannerParams.insertTemplates
	if len(templates) == 0 {
		// at this time INSERT is only supported if an insert template exists
		// Remove this conditional if there's any new case for INSERT
		return nil, fmt.Errorf("query not supported by vexec: %s", sqlparser.String(ins))
	}
	if len(templates) > 0 {
		match, err := vx.wr.env.Parser().QueryMatchesTemplates(vx.query, templates)
		if err != nil {
			return nil, err
		}
		if !match {
			return nil, fmt.Errorf("Query must match one of these templates: %s", strings.Join(templates, "; "))
		}
	}

	buf := sqlparser.NewTrackedBuffer(nil)
	buf.Myprintf("%v", ins)

	return &vexecPlan{
		opcode:      insertQuery,
		parsedQuery: buf.ParsedQuery(),
	}, nil

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Configure insertTemplates for the planner/table so the INSERT matches a supported shape
2. Route INSERTs through VTGate (normal query serving) instead of vexec
3. If adding a new supported INSERT case to vexec, replace this conditional with the real implementation

if len(planner.params().insertTemplates) == 0 {
    return fmt.Errorf("vexec INSERT not supported for this table; use VTGate")
}

if err := vexecExec(ctx, insQuery); err != nil {
    if strings.Contains(err.Error(), "query not supported by vexec") {
        // fall back to VTGate-based insert path
    }
    return err
}

When it happens

Trigger: Calling vexec with an INSERT statement while planner.params().insertTemplates is empty for the resolved table/planner — any INSERT hits this when no template exists.

Common situations: Using vexec as a generic SQL runner on a table whose planner was configured for UPDATE/DELETE only; new vexec use-cases added before an INSERT template was defined (the code comment even invites removing this conditional when a new INSERT case exists).

Related errors

• query not supported by vexec
• Query must match one of these templates: %s
• --batch-size only allowed when all queries are CREATE TABLE|
• cannot update immutable column
• unsupported query construct

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