vitessio/vitess · warning · ErrStaleVSchema

1105

1105

Error message

failed to update vschema as the session's version was stale; please try again

What it means

ErrStaleVSchema is an SQL-level error (errno 1105, sqlstate HY000) returned by VSchemaManager.UpdateVSchema when a session issues ALTER VSCHEMA ... with a version that no longer matches the current vschema — i.e. another update happened in between. The full user-visible message includes the errno/sqlstate and the offending query.

Source

Thrown at go/vt/vtgate/vschema_manager.go:40

	"fmt"
	"sync"

	"vitess.io/vitess/go/vt/graph"
	"vitess.io/vitess/go/vt/log"
	"vitess.io/vitess/go/vt/schema"
	"vitess.io/vitess/go/vt/sqlparser"
	"vitess.io/vitess/go/vt/srvtopo"
	"vitess.io/vitess/go/vt/topo"
	"vitess.io/vitess/go/vt/vterrors"
	"vitess.io/vitess/go/vt/vtgate/vindexes"

	topodatapb "vitess.io/vitess/go/vt/proto/topodata"
	vschemapb "vitess.io/vitess/go/vt/proto/vschema"
)

// The full SQL error that the user sees in their vtgate connection looks like this:
// failed to update vschema as the session's version was stale; please try again (errno 1105) (sqlstate HY000) during query: ALTER VSCHEMA DROP TABLE t864
var ErrStaleVSchema = errors.New("failed to update vschema as the session's version was stale; please try again")

// VSchemaManager is used to watch for updates to the vschema and to implement
// the DDL commands to add / remove vindexes
type VSchemaManager struct {
	mu                sync.Mutex
	currentSrvVschema *vschemapb.SrvVSchema
	currentVschema    *vindexes.VSchema
	serv              srvtopo.Server
	cell              string
	subscriber        func(vschema *vindexes.VSchema, stats *VSchemaStats)
	schema            SchemaInfo
	parser            *sqlparser.Parser
}

// SchemaInfo is an interface to schema tracker.
type SchemaInfo interface {
	Tables(ks string) map[string]*vindexes.TableInfo
	Views(ks string) map[string]sqlparser.TableStatement

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Retry the ALTER VSCHEMA statement as the error message suggests — the retry will re-read the current vschema
2. Coordinate vschema DDL so only one actor changes it at a time
3. Refresh the session (reconnect or re-acquire vschema version) before reapplying the DDL

Example fix

// before
-- one-shot DDL from a stale session, no retry
ALTER VSCHEMA DROP TABLE t864;
// after
-- retry loop on ErrStaleVSchema
for i := 0; i < 3; i++ {
    if _, err := db.Exec("ALTER VSCHEMA DROP TABLE t864"); err == nil || !strings.Contains(err.Error(), "version was stale") {
        break
    }
}

// fetch the current vschema version and refresh the session if it differs
if session.VSchemaVersion != manager.CurrentVersion() {
    session.RefreshVSchema()
}

_, err := conn.ExecContext(ctx, "ALTER VSCHEMA DROP TABLE t864")
if err != nil && strings.Contains(err.Error(), "version was stale") {
    // wait briefly, refresh session vschema, then retry
}

When it happens

Trigger: Running ALTER VSCHEMA ADD/DROP TABLE (or other vschema DDL) from a session whose cached vschema version is stale because another connection updated the vschema concurrently.

Common situations: Multiple operators or automation scripts applying vschema changes concurrently; long-lived sessions that held a session-local vschema copy while topology changes occurred.

Related errors

• value must be either a float64 (interpreted as seconds) or a
• flagutil: NewOptionalFlag requires a non-nil parse function
• flagutil: OptionalFlagValue has no parse function; use a con
• vindexType %q not found
• keyspace %s not found in vschema

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