apache/cassandra · error · IOException

When specifying the table for a snapshot, you must specify o

Error message

When specifying the table for a snapshot, you must specify one and only one keyspace

What it means

IllegalArgumentException from NodeProbe.takeSnapshot when a table argument is given but the keyspace list does not contain exactly one keyspace. Snapshots of a single table require unambiguous keyspace scope, so calls with a table plus zero or multiple keyspaces are rejected before contacting the snapshot MBean.

Source

Thrown at src/java/org/apache/cassandra/tools/NodeProbe.java:976

    {
        snapshotProxy.setSnapshotLinksPerSecond(throttle);
    }

    /**
     * Take a snapshot of all the keyspaces, optionally specifying only a specific column family.
     *
     * @param snapshotName the name of the snapshot.
     * @param table the table to snapshot or all on null
     * @param options Options (skipFlush for now)
     * @param keyspaces the keyspaces to snapshot
     */
    public void takeSnapshot(String snapshotName, String table, Map<String, String> options, String... keyspaces) throws IOException
    {
        if (table != null)
        {
            if (keyspaces.length != 1)
            {
                throw new IOException("When specifying the table for a snapshot, you must specify one and only one keyspace");
            }

            snapshotProxy.takeSnapshot(snapshotName, options, keyspaces[0] + "." + table);
        }
        else
            snapshotProxy.takeSnapshot(snapshotName, options, keyspaces);
    }

    /**
     * Take a snapshot of all column family from different keyspaces.
     *
     * @param snapshotName
     *            the name of the snapshot.
     * @param options
     *            Options (skipFlush for now)
     * @param tableList
     *            list of columnfamily from different keyspace in the form of ks1.cf1 ks2.cf2
     */

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Pass exactly one keyspace together with the table: nodetool snapshot -ks keyspace1 -cf users
2. If you need the same table in many keyspaces, run one snapshot per keyspace
3. Omit -cf if you intend to snapshot entire keyspaces

Example fix

// before
nodetool snapshot -cf users
// after
nodetool snapshot -ks keyspace1 -cf users

if (table != null && (keyspaces == null || keyspaces.length != 1))
    throw new IllegalArgumentException("table requires exactly one keyspace");

try {
    probe.takeSnapshot(snapshotName, table, options, keyspaces);
} catch (IOException e) {
    if (e.getMessage().contains("one and only one keyspace"))
        System.err.println("Pass exactly one keyspace when using -cf");
    else throw e;
}

When it happens

Trigger: nodetool snapshot -cf table (or NodeProbe.takeSnapshot with a non-null table) passing zero or multiple keyspaces — e.g. 'nodetool snapshot -cf users' without a keyspace, or with two or more keyspaces.

Common situations: Scripting snapshot calls with a table but forgetting the keyspace; assuming a table filter can span keyspaces in one command.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid throttle for snapshot_links_per_second: must be posi
• Cannot specify a repair as both paxos only and accord only
• You must supply a snapshot name.
• Snapshot name cannot contain
• Snapshot name '' is reserved

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