apache/cassandra · error · IllegalArgumentException

Unknown keyspace/table %s.%s

Error message

Unknown keyspace/table %s.%s

What it means

StandaloneUpgrader.main verifies that Schema.instance.getTableMetadata(options.keyspace, options.cf) resolves after offline initialization. If the keyspace/table pair is unknown, it throws IllegalArgumentException because the upgrader needs the table's metadata to rewrite SSTables.

Source

Thrown at src/java/org/apache/cassandra/tools/StandaloneUpgrader.java:68

public class StandaloneUpgrader
{
    private static final String TOOL_NAME = "sstableupgrade";
    private static final String DEBUG_OPTION  = "debug";
    private static final String HELP_OPTION  = "help";
    private static final String KEEP_SOURCE = "keep-source";

    public static void main(String args[])
    {
        Options options = Options.parseArgs(args);
        if (TEST_UTIL_ALLOW_TOOL_REINIT_FOR_TEST.getBoolean())
            DatabaseDescriptor.toolInitialization(false); //Necessary for testing
        else
            Util.initDatabaseDescriptor();
        ClusterMetadataService.initializeForTools(false);
        try
        {
            if (Schema.instance.getTableMetadata(options.keyspace, options.cf) == null)
                throw new IllegalArgumentException(String.format("Unknown keyspace/table %s.%s",
                                                                 options.keyspace,
                                                                 options.cf));

            Keyspace keyspace = Keyspace.openWithoutSSTables(options.keyspace);
            ColumnFamilyStore cfs = keyspace.getColumnFamilyStore(options.cf);

            OutputHandler handler = new OutputHandler.SystemOutput(false, options.debug);
            Directories.SSTableLister lister = cfs.getDirectories().sstableLister(Directories.OnTxnErr.THROW);
            if (options.snapshot != null)
                lister.onlyBackups(true).snapshots(options.snapshot);
            else
                lister.includeBackups(false);

            Collection<SSTableReader> readers = new ArrayList<>();

            // Upgrade sstables in id order
            for (Map.Entry<Descriptor, Set<Component>> entry : lister.sortedList())
            {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Confirm the exact keyspace/table names via cqlsh and correct the arguments
  2. Run the tool on a node that has the table in its schema (correct config/data paths)
  3. Restore the schema if the table was dropped and the sstables must be upgraded

Example fix

// before
StandaloneUpgrader ks1 Usres /path/to/snapshots
// after
StandaloneUpgrader ks1 users /path/to/snapshots
Defensive patterns

Strategy: validation

Validate before calling

if (Schema.instance.getTableMetadata(ks, cf) == null)
    throw new IllegalArgumentException("Unknown keyspace/table " + ks + "." + cf);

Try / catch

try { StandaloneUpgrader.main(args); }
catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unknown keyspace/table")) {
        // correct keyspace/cf arguments
    } else throw e;
}

Prevention

When it happens

Trigger: Running the standalone upgrader with a --keyspace/--cf pair that does not exist in the loaded schema.

Common situations: Typo or wrong-case table name; upgrading sstables copied from a cluster whose schema differs; table dropped before the tool ran; running against a node that hasn't loaded the schema.

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/9afab25c0d99fd4e. Report an issue: GitHub.