apache/cassandra · critical · IllegalArgumentException

Invalid sstable file

Error message

Invalid sstable file %s: the 'id' part (%s) of the name doesn't parse as a valid unique identifier

What it means

Modern sstable names embed a globally unique identifier as the second token, parsed by SSTableIdFactory.instance.fromString(). If that parsing throws a RuntimeException, validateAndExtractInfo wraps it in this invalidSSTable exception: the 'id' token does not represent a valid unique identifier, so the descriptor cannot be constructed.

Solutions

1. Fix the filename if the id token was corrupted or renamed; restore the original name from backup/snapshot metadata.
2. Confirm the file comes from a compatible Cassandra version that emits the expected SSTableId format.
3. Use the upgrade tooling (upgradeSSTables) to regenerate files in the expected naming scheme.
4. Remove files that are not genuine sstable components of this table from the data directory.

Example fix

// before
mc-notanid-big-Data.db    // second token 'notanid' is not an SSTableId
// after
mc-1g-7big-Data.db        // token parses as a valid unique identifier (per SSTableIdFactory)

try { SSTableIdFactory.instance.fromString(filenameTokens.get(1)); }
catch (RuntimeException e) { throw new IllegalStateException("Bad sstable id token: " + filenameTokens.get(1)); }

try { Descriptor.Info info = Descriptor.fromFilename(file); }
catch (Throwable e) { if (e.getMessage() != null && e.getMessage().contains("doesn't parse as a valid unique identifier")) { /* restore original filename from backup */ } else throw e; }

When it happens

Trigger: Descriptor.info(file)/fromFilename where the second underscore-token of the filename is not parseable as an SSTableId (e.g. legacy numeric generation where the build expects UUID-like ids, or corrupted/renamed tokens).

Common situations: Mixing sstable naming generations (old numeric-generation files vs new UUID-id files) after upgrade or restore; hand-edited filenames; copying files from incompatible versions.

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

Appendix: source

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

    }

    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));
        }
        catch (RuntimeException e)
        {
            throw invalidSSTable(name, "the 'id' part (%s) of the name doesn't parse as a valid unique identifier", tokens.get(1));
        }

        SSTableFormat<?, ?> format = formatFromName(name, tokens);
        Component component = Component.parse(tokens.get(3), format);

        Version version = format.getVersion(versionString);
        if (!version.isCompatible())
            throw invalidSSTable(name, "incompatible sstable version (%s); you should have run upgradesstables before upgrading", versionString);

        return new SSTableInfo(version, id, component);
    }

    private static class SSTableInfo
    {
        final Version version;
        final SSTableId id;
        final Component component;

View on GitHub (pinned to 88fd0f6a0e)