apache/cassandra · error · IllegalArgumentException

Cannot take a snapshot on secondary index or invalid column…

Error message

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

What it means

parseEntitiesForSnapshot throws IllegalArgumentException when an entity string is neither 'keyspace.table' with a valid length-2 split nor a recognized index name: the caller must supply a column family in the form keyspace.columnfamily. Secondary indexes can only be referenced indirectly as valid index names; anything else (bare table name without keyspace, extra dots, plain garbage) lands here.

Solutions

1. Always qualify the table: nodetool snapshot -ks <keyspace> -cf <table> or pass 'keyspace.table' entities.
2. Check for stray characters (extra dots, spaces) in entity strings.
3. To snapshot a whole keyspace, use -ks alone rather than malformed per-table entities.

Example fix

// before
nodetool snapshot --table users
// after
nodetool snapshot --keyspace keyspace1 --table users

if (!entity.matches("[^.]+\.[^.]+") && !isKnownIndex(entity))
    throw new IllegalArgumentException("Entity must be keyspace.columnfamily: " + entity);

try { takeSnapshot(entities); } catch (IllegalArgumentException e) { if (e.getMessage().contains("form of keyspace.columnfamily")) throw new IllegalArgumentException("Bad snapshot entity format: " + entities, e); throw e; }

When it happens

Trigger: nodetool snapshot --table mytable (no keyspace prefix); entity strings with more than one dot; passing an index-like name when the split produces unexpected token counts via JMX/programmatic takeSnapshot calls.

Common situations: Scripts omitting the keyspace because they assumed a default keyspace is in scope; users trying to snapshot a secondary index directly; JMX invocations with wrong entity format (comma vs space separation).

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• You must supply a keyspace name
• You must supply a table name
• A range supplied to SSTableCursorReader ends before it…
• Argument must have keyspace and table values.
• arguments for -F are json, yaml, table only.

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

Appendix: source

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

                    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());
                }
            }
            else if (entities != null)
            {
                for (String keyspace : entities)
                {

View on GitHub (pinned to 88fd0f6a0e)