apache/cassandra · error · IllegalArgumentException

Unknown keyspace %s

Error message

Unknown keyspace %s

What it means

StandaloneScrubber.main validates the keyspace name before opening it: Schema.instance.getKeyspaceMetadata(keyspaceName) must return non-null. If the keyspace does not exist in the loaded schema, it throws IllegalArgumentException, since scrubbing requires a valid keyspace definition.

Source

Thrown at src/java/org/apache/cassandra/tools/StandaloneScrubber.java:97

    /**
     * This option was logically removed from the code, but to avoid breaking backwards compatability the option remains
     */
    private static final String HEADERFIX_OPTION = "header-fix";

    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.getKeyspaceMetadata(options.keyspaceName) == null)
                throw new IllegalArgumentException(String.format("Unknown keyspace %s", options.keyspaceName));

            // Do not load sstables since they might be broken
            Keyspace keyspace = Keyspace.openWithoutSSTables(options.keyspaceName);

            ColumnFamilyStore cfs = null;
            for (ColumnFamilyStore c : keyspace.getValidColumnFamilies(true, false, options.cfName))
            {
                if (c.name.equals(options.cfName))
                {
                    cfs = c;
                    break;
                }
            }

            if (cfs == null)
                throw new IllegalArgumentException(String.format("Unknown table %s.%s",
                                                                  options.keyspaceName,
                                                                  options.cfName));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Check the keyspace name with cqlsh (DESCRIBE keyspaces) and fix the argument
  2. Ensure the tool is run against the node's real schema (correct config/data dirs)
  3. Remove the tool invocation for keyspaces that no longer exist

Example fix

// before
StandaloneScrubber ks2 users
// after
StandaloneScrubber ks1 users
Defensive patterns

Strategy: validation

Validate before calling

if (Schema.instance.getKeyspaceMetadata(ks) == null)
    throw new IllegalArgumentException("Unknown keyspace " + ks);

Try / catch

try { StandaloneScrubber.main(args); }
catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown keyspace ")) {
        // correct the --ks argument
    } else throw e;
}

Prevention

When it happens

Trigger: Running the standalone scrubber with a --ks (keyspace) option naming a keyspace absent from the offline-loaded schema.

Common situations: Typo or wrong-case keyspace name; scrubbing sstables copied from another cluster whose keyspace doesn't exist locally; keyspace dropped before running the tool.

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/518d72e75a37a8f2. Report an issue: GitHub.