What causes "Cassandra keyspace not found: %s" in t8y2/dbx?

Verify the keyspace exists: run `DESCRIBE keyspaces;` in cqlsh or SELECT keyspace_name FROM system_schema.keyspaces;

Cassandra keyspace not found: %s

Error message

Cassandra keyspace not found: %s

What it means

This error is returned by keyspaceMetadata in the Cassandra driver after session.KeyspaceMetadata(schema) succeeds but yields a nil metadata object. It signals that the requested keyspace name does not exist in the cluster (or its metadata could not be resolved), so no schema information can be returned to tableMetadata/listTables callers.

Source

Thrown at agents/drivers/cassandra-go/metadata.go:187

func (s *server) allKeyspaceMetadata() (map[string]*gocql.KeyspaceMetadata, error) {
	session, err := s.runtime.sessionFor("")
	if err != nil {
		return nil, err
	}
	return session.AllKeyspaceMetadata()
}

func (s *server) keyspaceMetadata(schema string) (*gocql.KeyspaceMetadata, error) {
	session, err := s.runtime.sessionFor("")
	if err != nil {
		return nil, err
	}
	metadata, err := session.KeyspaceMetadata(schema)
	if err != nil {
		return nil, err
	}
	if metadata == nil {
		return nil, fmt.Errorf("Cassandra keyspace not found: %s", schema)
	}
	return metadata, nil
}

func (s *server) tableMetadata(schema, table string) (*gocql.TableMetadata, error) {
	keyspace, err := s.keyspaceMetadata(schema)
	if err != nil {
		return nil, err
	}
	metadata := keyspace.Tables[table]
	if metadata == nil {
		return nil, fmt.Errorf("Cassandra table not found: %s.%s", schema, table)
	}
	return metadata, nil
}

func (s *server) listDatabases() ([]databaseInfo, error) {
	metadata, err := s.allKeyspaceMetadata()

View on GitHub (pinned to c0390bff16)

Solutions

Verify the keyspace exists: run `DESCRIBE keyspaces;` in cqlsh or SELECT keyspace_name FROM system_schema.keyspaces;
Fix the keyspace name passed to the driver/API call, matching exact case (Cassandra keyspaces are case-sensitive when quoted)
Set a valid keyspace in the connection config so callers that omit one resolve to the intended keyspace
Create the missing keyspace if it should exist (CREATE KEYSPACE ...)

Example fix

// before
meta, err := srv.ListTables(ctx, "sale")
// after
meta, err := srv.ListTables(ctx, "sales") // keyspace verified via SELECT keyspace_name FROM system_schema.keyspaces

Defensive patterns

Strategy: validation

Validate before calling

var exists bool
if err := session.Query("SELECT count(*) FROM system_schema.keyspaces WHERE keyspace_name = ?", ks).Scan(&exists); err != nil || !exists {
	return fmt.Errorf("keyspace %q does not exist", ks)
}

Try / catch

meta, err := srv.ListTables(ctx, ks)
if err != nil {
	if strings.Contains(err.Error(), "Cassandra keyspace not found") {
		// prompt user / fall back to default keyspace
		return fmt.Errorf("keyspace %q not found; available: %v", ks, listKeyspaces(session))
	}
	return err
}

Prevention

Always verify the keyspace exists in system_schema.keyspaces before metadata calls
Pin the keyspace in connection config per environment
Validate keyspace names with exact case checks before calling the driver
Keep keyspace names in one shared config constant rather than hard-coding strings

When it happens

Trigger: Calling ListTables, GetColumns, GetTableDDL or any metadata API with a keyspace name that does not exist in the Cassandra cluster; gocql's KeyspaceMetadata returns (nil, nil) for a missing keyspace and this driver converts that into an explicit error.

Common situations: Typo in the keyspace name; connecting without specifying a keyspace so an empty/default name is used; keyspace was dropped or renamed; environment mismatch (dev keyspace vs prod keyspace); case-sensitive keyspace names in system_schema.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/33229c51634bbe2a. Report an issue: GitHub.