apache/cassandra · error · IllegalArgumentException

Unknown keyspace/table %s.%s

Error message

Unknown keyspace/table %s.%s

What it means

StandaloneSSTableUtil.main resolves the target table via Schema.instance.getTableMetadata(keyspaceName, cfName) after initializing the database descriptor offline. If no table metadata exists for the given keyspace/table pair, it throws IllegalArgumentException, because the offline operation cannot proceed without a valid table definition.

Source

Thrown at src/java/org/apache/cassandra/tools/StandaloneSSTableUtil.java:59

    private static final String TYPE_OPTION  = "type";
    private static final String OP_LOG_OPTION  = "oplog";
    private static final String VERBOSE_OPTION  = "verbose";
    private static final String DEBUG_OPTION  = "debug";
    private static final String HELP_OPTION  = "help";
    private static final String CLEANUP_OPTION = "cleanup";

    public static void main(String args[])
    {

        Options options = Options.parseArgs(args);
        try
        {
            // load keyspace descriptions.
            Util.initDatabaseDescriptor();
            ClusterMetadataService.initializeForTools(false);
            TableMetadata metadata = Schema.instance.getTableMetadata(options.keyspaceName, options.cfName);
            if (metadata == null)
                throw new IllegalArgumentException(String.format("Unknown keyspace/table %s.%s",
                                                                 options.keyspaceName,
                                                                 options.cfName));

            OutputHandler handler = new OutputHandler.SystemOutput(options.verbose, options.debug);

            if (options.cleanup)
            {
                handler.output("Cleaning up...");
                LifecycleTransaction.removeUnfinishedLeftovers(metadata);
            }
            else
            {
                handler.output("Listing files...");
                listFiles(options, metadata, handler);
            }

            System.exit(0);
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Verify the exact keyspace and table names (cqlsh: DESCRIBE keyspaces / DESCRIBE tables)
  2. Remember names are case-sensitive when quoted; unquoted names are lowercased
  3. Run the tool with the correct schema so TableMetadata can be resolved (correct data/config directories)
  4. If the table was dropped, restore its schema before running offline tools

Example fix

// before
StandaloneSSTableUtil --keyspace KS1 --table UserS
// after
StandaloneSSTableUtil --keyspace ks1 --table users
Defensive patterns

Strategy: validation

Validate before calling

// Before invoking the tool:
boolean exists = Schema.instance.getTableMetadata(ks, cf) != null;
if (!exists) throw new IllegalArgumentException("Unknown keyspace/table " + ks + "." + cf);

Try / catch

try { StandaloneSSTableUtil.main(args); }
catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unknown keyspace/table")) {
        // prompt for correct keyspace/table
    } else throw e;
}

Prevention

When it happens

Trigger: Running a standalone SSTable tool (e.g. upgradesstables/scrub variants) with a --keyspace/--table combination that does not exist in the schema (schema files loaded offline).

Common situations: Typo in keyspace or table name; case-sensitivity mistake (unquoted identifiers are lowercased in CQL); running the tool against the wrong data directory or without the schema being loadable; table dropped between snapshot and tool run.

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/780ba2a51b73143c. Report an issue: GitHub.