apache/cassandra · warning · IllegalStateException

Unknown keyspace . This can occur if the keyspace is being…

Error message

Unknown keyspace %s. This can occur if the keyspace is being dropped.

What it means

SegmentsSystemView.forEachIndex (used by data()) walks user keyspaces and live instances to enumerate SAI segments. If a keyspace exists in metadata but its live instance is missing — normally because it is being dropped concurrently — it throws IllegalStateException("Unknown keyspace %s. This can occur if the keyspace is being dropped.").

Solutions

Retry the virtual-table read after the drop completes
Pause schema mutations while polling virtual tables
Upgrade to a build that skips keyspaces with no live instance

Example fix

null

Defensive patterns

Strategy: retry

Try / catch

try {
    rs = session.execute(querySegmentsView);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unknown keyspace")) {
        // retry after backoff; keyspace likely being dropped
    } else throw e;
}

Prevention

Pause segment monitoring during keyspace drops
Use retry-with-backoff for virtual-table scans
Coordinate schema changes across tools sharing the cluster

When it happens

Trigger: SELECT from the segments virtual table during concurrent DROP KEYSPACE; metadata iteration yields the keyspace but the live instance lookup returns null inside forEachIndex.

Common situations: Dashboard/monitoring polling of system_views.segments during schema changes; parallel test frameworks dropping keyspaces while others inspect segment views.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/3901bd2bc9446806. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/virtual/SegmentsSystemView.java:107

        SimpleDataSet dataset = new SimpleDataSet(metadata());

        forEachIndex(index -> {
            for (SSTableIndex sstableIndex : index.view())
            {
                sstableIndex.populateSegmentView(dataset);
            }
        });

        return dataset;
    }

    private void forEachIndex(Consumer<StorageAttachedIndex> process)
    {
        for (KeyspaceMetadata ks : Schema.instance.getUserKeyspaces())
        {
            Keyspace keyspace = Schema.instance.getKeyspaceInstance(ks.name);
            if (keyspace == null)
                throw new IllegalStateException("Unknown keyspace " + ks + ". This can occur if the keyspace is being dropped.");

            for (ColumnFamilyStore cfs : keyspace.getColumnFamilyStores())
            {
                StorageAttachedIndexGroup group = StorageAttachedIndexGroup.getIndexGroup(cfs);

                if (group != null)
                    group.getIndexes().stream().map(index -> (StorageAttachedIndex) index).forEach(process);
            }
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)