{"record":{"id":"ebba24ab87772355","repo":"vitessio/vitess","slug":"keyspace-s-not-found-in-vschema","errorCode":null,"errorMessage":"keyspace %s not found in vschema","messagePattern":"keyspace (.+?) not found in vschema","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtgate/vindexes/vschema.go","lineNumber":1018,"sourceCode":"\terrMsgFormat := \"invalid table name: '%s', it must be of the \"\n\tif allowUnqualified {\n\t\terrMsgFormat = errMsgFormat + \"unqualified form <table_name> or the \"\n\t}\n\terrMsgFormat = errMsgFormat + \"qualified form <keyspace_name>.<table_name> (dots are not allowed in either name)\"\n\n\t// It's possible to have a database or table name with a dot in it, but\n\t// that's not otherwise supported within vitess today\n\tarr := strings.Split(tableName, \".\")\n\tswitch len(arr) {\n\tcase 1:\n\t\tif allowUnqualified {\n\t\t\treturn \"\", arr[0], nil\n\t\t}\n\tcase 2:\n\t\treturn arr[0], arr[1], nil\n\t}\n\t// Using fmt.Errorf instead of vterrors here because this error is always wrapped in vterrors.\n\treturn \"\", \"\", fmt.Errorf(errMsgFormat, tableName)\n}\n\nfunc parseTable(tableName string) (sqlparser.TableName, error) {\n\tkeyspace, tableName, err := extractTableParts(tableName, true /* allowUnqualified */)\n\tif err != nil {\n\t\treturn sqlparser.TableName{}, err\n\t}\n\treturn sqlparser.TableName{\n\t\tQualifier: sqlparser.NewIdentifierCS(keyspace),\n\t\tName:      sqlparser.NewIdentifierCS(tableName),\n\t}, nil\n}\n\nfunc buildRoutingRule(source *vschemapb.SrvVSchema, vschema *VSchema, parser *sqlparser.Parser) {\n\tvar err error\n\tif source.RoutingRules == nil {\n\t\treturn\n\t}","sourceCodeStart":1000,"sourceCodeEnd":1036,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtgate/vindexes/vschema.go#L1000-L1036","documentation":"During vschema table-name resolution (extractTableParts/parseTable path in vschema.go) the qualified table's keyspace cannot be resolved against the loaded vschema; the message is 'keyspace %s not found in vschema'. The vschema only declares certain keyspaces, so a table reference pointing at an unknown keyspace fails resolution and the query cannot be routed.","triggerScenarios":"A SQL query referencing keyspace.table where that keyspace is absent from the vschema loaded by VTGate; lookup/foreign-key/vindex code resolving a table name whose first qualifier is not a known keyspace.","commonSituations":"Typo in the keyspace qualifier; query sent to a VTGate that hasn't had that keyspace's vschema applied yet; keyspace renamed or dropped; serving from a cell where the vschema isn't loaded; tests constructing table names with a wrong prefix.","solutions":["Check the loaded vschema (vtctl GetVSchema) and confirm the keyspace is present.","Apply or fix the vschema for the missing keyspace (vtctl ApplyVSchema).","Correct the keyspace qualifier in the query or remove it to use the default keyspace.","Verify the query is hitting the right VTGate/environment (test vs prod keyspace names).","If the keyspace was renamed, update clients and vschema references (routing rules, lookup tables)."],"exampleFix":"// before (vschema missing \"customer\")\nSELECT * FROM customer.orders;\n// after: add vschema for customer or use the defined keyspace\nvtctlclient ApplyVSchema -vschema='{ \"keyspaces\": { \"customer\": { ... } } }'","handlingStrategy":"validation","validationCode":"// before running the query, confirm keyspace exists:\n// vtctlclient GetVSchema <keyspace>   (must succeed)\n// or in Go:\nif vs.GetKeyspace(ksName) == nil {\n    return fmt.Errorf(\"keyspace %s not loaded; apply vschema first\", ksName)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"not found in vschema\") {\n    // check GetVSchema for the keyspace, apply it, then retry\n    return retryAfterVSchemaApply(query)\n}","preventionTips":["Apply vschema for every keyspace before serving queries","Keep keyspace names consistent across deploy configs","Use routing rules when renaming keyspaces","Verify with GetVSchema in deployment smoke tests"],"tags":["vtgate","vschema","keyspace","routing"],"backgroundTag":"keyspace-not-found-in-vschema","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}