vitessio/vitess · error

keyspace %s not found in vschema

Error message

keyspace %s not found in vschema

What it means

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.

Source

Thrown at go/vt/vtgate/vindexes/vschema.go:1018

	errMsgFormat := "invalid table name: '%s', it must be of the "
	if allowUnqualified {
		errMsgFormat = errMsgFormat + "unqualified form <table_name> or the "
	}
	errMsgFormat = errMsgFormat + "qualified form <keyspace_name>.<table_name> (dots are not allowed in either name)"

	// It's possible to have a database or table name with a dot in it, but
	// that's not otherwise supported within vitess today
	arr := strings.Split(tableName, ".")
	switch len(arr) {
	case 1:
		if allowUnqualified {
			return "", arr[0], nil
		}
	case 2:
		return arr[0], arr[1], nil
	}
	// Using fmt.Errorf instead of vterrors here because this error is always wrapped in vterrors.
	return "", "", fmt.Errorf(errMsgFormat, tableName)
}

func parseTable(tableName string) (sqlparser.TableName, error) {
	keyspace, tableName, err := extractTableParts(tableName, true /* allowUnqualified */)
	if err != nil {
		return sqlparser.TableName{}, err
	}
	return sqlparser.TableName{
		Qualifier: sqlparser.NewIdentifierCS(keyspace),
		Name:      sqlparser.NewIdentifierCS(tableName),
	}, nil
}

func buildRoutingRule(source *vschemapb.SrvVSchema, vschema *VSchema, parser *sqlparser.Parser) {
	var err error
	if source.RoutingRules == nil {
		return
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the loaded vschema (vtctl GetVSchema) and confirm the keyspace is present.
2. Apply or fix the vschema for the missing keyspace (vtctl ApplyVSchema).
3. Correct the keyspace qualifier in the query or remove it to use the default keyspace.
4. Verify the query is hitting the right VTGate/environment (test vs prod keyspace names).
5. If the keyspace was renamed, update clients and vschema references (routing rules, lookup tables).

Example fix

// before (vschema missing "customer")
SELECT * FROM customer.orders;
// after: add vschema for customer or use the defined keyspace
vtctlclient ApplyVSchema -vschema='{ "keyspaces": { "customer": { ... } } }'

// before running the query, confirm keyspace exists:
// vtctlclient GetVSchema <keyspace>   (must succeed)
// or in Go:
if vs.GetKeyspace(ksName) == nil {
    return fmt.Errorf("keyspace %s not loaded; apply vschema first", ksName)
}

if err != nil && strings.Contains(err.Error(), "not found in vschema") {
    // check GetVSchema for the keyspace, apply it, then retry
    return retryAfterVSchemaApply(query)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 1105
• SrvVSchema has no entry for keyspace %v
• GetVSchema(keyspace = %s): %w
• EnsureVSchema(%v) failed: %v
• SaveVSchema(%v) = %w

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