apache/cassandra · error · java.lang.IllegalArgumentException

Invalid sstable file

Error message

Invalid sstable file %s: the name doesn't look like a supported sstable file name

What it means

Descriptor.filenameTokens() throws this generic IllegalArgumentException when a file name's token count/layout matches neither the current nor the recognizable legacy SSTable naming scheme, so Cassandra cannot even classify it as an unsupported-version SSTable. It indicates the file is not a valid component file for this directory (wrong placement, truncated name, or unrelated file).

Solutions

1. Inspect the offending file name from the message; if it is not a Cassandra component, move it out of the data directory
2. If it is a real component with a corrupted name, restore the correct name matching <table>-<uuid or version>-<gen>-<component> for your version, or redownload/recopy the file
3. Run a fresh backup restore rather than attempting to hand-patch names; verify directory layout (per-table subdirectories on 3.0+)

if (!file.getName().matches("[a-zA-Z0-9_]+-([a-z0-9-]+-)?\\d+-(big-)?[A-Za-z]+[.-].*"))
    System.out.println("Not a recognizable sstable component: " + file.getName());

try { Descriptor d = Descriptor.fromFilename(file); }
catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid sstable file"))
        // quarantine or remove the unparseable file
}

When it happens

Trigger: Files with malformed names sitting in an SSTable data directory while code iterates the directory calling Descriptor.tokens/fromFilename — e.g. partially renamed files, hand-edited names, non-SSTable files dropped into the table folder, or names missing gen/component segments.

Common situations: Manual file manipulation or scripts that rename SSTables; interrupted copy operations; foreign files (logs, editors' temp files) inside data directories.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Invalid sstable file
• Invalid sstable file
• Invalid sstable file
• Invalid sstable file
• Invalid sstable file

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/sstable/Descriptor.java:409

        SSTableInfo info = validateAndExtractInfo(file);
        return Pair.create(new Descriptor(info.version, parentOf(file.name(), file), keyspace, table, info.id), info.component);
    }

    private static List<String> filenameTokens(String name)
    {
        List<String> tokens = filenameSplitter.splitToList(name);
        int size = tokens.size();

        if (size != 4)
        {
            // This is an invalid sstable file for this version. But to provide a more helpful error message, we detect
            // old format sstable, which had the format:
            //   <keyspace>-<table>-(tmp-)?<version>-<gen>-<component>
            // Note that we assume it's an old format sstable if it has the right number of tokens: this is not perfect
            // but we're just trying to be helpful, not perfect.
            if (size == 5 || size == 6)
                throw new IllegalArgumentException(String.format("%s is of version %s which is now unsupported and cannot be read.", name, tokens.get(size - 3)));
            throw new IllegalArgumentException(String.format("Invalid sstable file %s: the name doesn't look like a supported sstable file name", name));
        }
        return tokens;
    }

    private static SSTableInfo validateAndExtractInfo(File file)
    {
        String name = file.name();
        List<String> tokens = filenameTokens(name);

        String versionString = tokens.get(0);
        if (!Version.validate(versionString))
            throw invalidSSTable(name, "invalid version %s", versionString);

        SSTableId id;
        try
        {
            id = SSTableIdFactory.instance.fromString(tokens.get(1));
        }

View on GitHub (pinned to 88fd0f6a0e)