{"record":{"id":"a3ecbd13e5cc2748","repo":"vitessio/vitess","slug":"1105","errorCode":"1105","errorMessage":"failed to update vschema as the session's version was stale; please try again","messagePattern":"failed to update vschema as the session's version was stale; please try again","errorType":"error_code","errorClass":"ErrStaleVSchema","httpStatus":null,"severity":"warning","filePath":"go/vt/vtgate/vschema_manager.go","lineNumber":40,"sourceCode":"\t\"fmt\"\n\t\"sync\"\n\n\t\"vitess.io/vitess/go/vt/graph\"\n\t\"vitess.io/vitess/go/vt/log\"\n\t\"vitess.io/vitess/go/vt/schema\"\n\t\"vitess.io/vitess/go/vt/sqlparser\"\n\t\"vitess.io/vitess/go/vt/srvtopo\"\n\t\"vitess.io/vitess/go/vt/topo\"\n\t\"vitess.io/vitess/go/vt/vterrors\"\n\t\"vitess.io/vitess/go/vt/vtgate/vindexes\"\n\n\ttopodatapb \"vitess.io/vitess/go/vt/proto/topodata\"\n\tvschemapb \"vitess.io/vitess/go/vt/proto/vschema\"\n)\n\n// The full SQL error that the user sees in their vtgate connection looks like this:\n// 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\nvar ErrStaleVSchema = errors.New(\"failed to update vschema as the session's version was stale; please try again\")\n\n// VSchemaManager is used to watch for updates to the vschema and to implement\n// the DDL commands to add / remove vindexes\ntype VSchemaManager struct {\n\tmu                sync.Mutex\n\tcurrentSrvVschema *vschemapb.SrvVSchema\n\tcurrentVschema    *vindexes.VSchema\n\tserv              srvtopo.Server\n\tcell              string\n\tsubscriber        func(vschema *vindexes.VSchema, stats *VSchemaStats)\n\tschema            SchemaInfo\n\tparser            *sqlparser.Parser\n}\n\n// SchemaInfo is an interface to schema tracker.\ntype SchemaInfo interface {\n\tTables(ks string) map[string]*vindexes.TableInfo\n\tViews(ks string) map[string]sqlparser.TableStatement","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtgate/vschema_manager.go#L22-L58","documentation":"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.","triggerScenarios":"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.","commonSituations":"Multiple operators or automation scripts applying vschema changes concurrently; long-lived sessions that held a session-local vschema copy while topology changes occurred.","solutions":["Retry the ALTER VSCHEMA statement as the error message suggests — the retry will re-read the current vschema","Coordinate vschema DDL so only one actor changes it at a time","Refresh the session (reconnect or re-acquire vschema version) before reapplying the DDL"],"exampleFix":"// before\n-- one-shot DDL from a stale session, no retry\nALTER VSCHEMA DROP TABLE t864;\n// after\n-- retry loop on ErrStaleVSchema\nfor i := 0; i < 3; i++ {\n    if _, err := db.Exec(\"ALTER VSCHEMA DROP TABLE t864\"); err == nil || !strings.Contains(err.Error(), \"version was stale\") {\n        break\n    }\n}","handlingStrategy":"retry","validationCode":"// fetch the current vschema version and refresh the session if it differs\nif session.VSchemaVersion != manager.CurrentVersion() {\n    session.RefreshVSchema()\n}","typeGuard":null,"tryCatchPattern":"_, err := conn.ExecContext(ctx, \"ALTER VSCHEMA DROP TABLE t864\")\nif err != nil && strings.Contains(err.Error(), \"version was stale\") {\n    // wait briefly, refresh session vschema, then retry\n}","preventionTips":["Serialize vschema DDL through a single operator or lock","Refresh session vschema after long idle periods before issuing DDL","Wrap vschema DDL in a bounded retry loop on this specific error"],"tags":["vtgate","vschema","concurrency","sql-error"],"backgroundTag":"stale-vschema-version","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}