apache/cassandra · critical · IllegalArgumentException

Invalid sstable file

Error message

Invalid sstable file ${name}: invalid version %s

What it means

SSTable filenames begin with a version token (e.g. 'ka', 'mc', 'md'). validateAndExtractInfo extracts token 0 and validates it via Version.validate; on failure this invalidSSTable exception is thrown. It means the first filename token is not a known sstable format version, so the file cannot be attributed to any readable version.

Solutions

1. Check the filename and restore the correct version token if it was renamed or corrupted.
2. Verify the file actually is a Cassandra sstable component (naming scheme: version-id-generation-format-component).
3. Upgrade Cassandra if the file was written by a newer version whose version string this build rejects.
4. Remove foreign/corrupt files from the data directory and let a repair/refresh regenerate data.

Example fix

// before
mytable-xy7f_0abc_1big-Data.db   // 'xy7f' is not a version token
// after
mc-1-big-Data.db                  // valid version token ('mc') as first part

String versionToken = filename.split("-")[0];
if (!Version.validate(versionToken))
    throw new IllegalStateException("Not a valid sstable version token: " + versionToken);

try { Descriptor.Info info = Descriptor.fromFilename(file); }
catch (Throwable e) { if (e.getMessage() != null && e.getMessage().contains("invalid version")) { /* fix filename or upgrade version */ } else throw e; }

When it happens

Trigger: Descriptor.info(file)/fromFilename on a file whose first name token is not a valid version string — corrupted filenames, files renamed without preserving the version token, or files from a much newer/unknown version.

Common situations: Hand-edited sstable names during manual repairs; files placed in a table directory that don't belong (foreign artifacts); restoring data from a newer major version into an older node.

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

Appendix: source

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

            // 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));
        }
        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);

View on GitHub (pinned to 88fd0f6a0e)