apache/cassandra · error · IllegalArgumentException

Unknown index

Error message

Unknown index 

What it means

When a snapshot entity names a secondary index (keyspace.index_name), parseEntitiesForSnapshot looks up the index among the table's IndexManager indexes; if the name doesn't match any known index it throws IllegalArgumentException('Unknown index <entity>'). Snapshots can target built-in (CassandraIndex) index backing tables, but only indexes that actually exist on that table.

Solutions

1. Verify the index exists: DESCRIBE the table or check system_schema.indexes for the exact name.
2. If the goal is the underlying data, snapshot the base table instead — index backing SSTables are included automatically.
3. Recreate the index if it was dropped; custom (non-CassandraIndex) indexes cannot be targeted directly this way.

Example fix

// before
nodetool snapshot -ks ks -cf users_by_old_idx   # index dropped
// after
nodetool snapshot -ks ks -cf users   # base table includes indexes

TableMetadata tm = Schema.instance.validateTable(ks, table);
if (tm == null || !tm.indexes.hasIndex(indexName))
    throw new IllegalArgumentException("Index not found: " + indexName);

try { snapshot(entity); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown index")) { snapshotBaseTable(ks, table); } else throw e; }

When it happens

Trigger: nodetool snapshot --table ks.index_name where the index doesn't exist on the table, was dropped, or is a custom/SAI index whose handler isn't a CassandraIndex; typos in index names (often with the table's generated 6-char suffix confusion).

Common situations: Snapshotting index backing tables by their internal name (e.g. users_by_email_idx) after the index was recreated with a different name; assuming all index types are snapshot-targetable; case-sensitivity mistakes on quoted identifiers.

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

• An error occurred while scrubbing the partition with key
• can not take ephemeral snapshot
• Cannot create ENTRIES index on frozen map clustering column
• Cannot create index on
• Cannot create () index on frozen column . Frozen…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/snapshot/TakeSnapshotTask.java:237

                // special case for index which we can not normally create a snapshot for
                // but a snapshot is apparently taken before a secondary index is scrubbed,
                // so we preserve this behavior
                else if (splitted.length == 3)
                {
                    String keyspaceName = splitted[0];
                    String tableName = splitted[1];

                    Keyspace validKeyspace = Keyspace.getValidKeyspace(keyspaceName);
                    ColumnFamilyStore existingTable = validKeyspace.getColumnFamilyStore(tableName);
                    Index indexByName = existingTable.indexManager.getIndexByName(splitted[2]);
                    if (indexByName instanceof CassandraIndex)
                    {
                        ColumnFamilyStore indexCfs = ((CassandraIndex) indexByName).getIndexCfs();
                        entitiesForSnapshot.add(indexCfs);
                    }
                    else
                    {
                        throw new IllegalArgumentException("Unknown index " + entity);
                    }
                }
                else
                {
                    throw new IllegalArgumentException("Cannot take a snapshot on secondary index or invalid column " +
                                                       "family name. You must supply a column family name in the " +
                                                       "form of keyspace.columnfamily");
                }
            }
        }
        else
        {
            if (entities != null && entities.length == 0)
            {
                for (Keyspace keyspace : Keyspace.all())
                {
                    entitiesForSnapshot.addAll(keyspace.getColumnFamilyStores());
                }

View on GitHub (pinned to 88fd0f6a0e)