apache/cassandra · critical · IllegalArgumentException

Invalid sstable file

Error message

Invalid sstable file ${name}: unknown 'format' part (%s)

What it means

SSTable filenames encode the format identifier in their name tokens. formatFromName reads the third token and looks it up in DatabaseDescriptor.getSSTableFormats(); if no registered SSTableFormat matches the string, this invalidSSTable exception is thrown. It means the file was written by a format this Cassandra build does not know, or the filename is malformed/corrupted.

Solutions

1. Use a Cassandra build that supports the format named in the file (upgrade if files use bti/experimental formats).
2. Fix the filename if it was manually renamed and the format token is wrong.
3. Check DatabaseDescriptor.getSSTableFormats() (cassandra.yaml sstable_formats config) to confirm the format is registered/enabled.
4. If files are unneeded/corrupt, remove or regenerate them with SSTableWriter on the target version.

Example fix

// before
// cassandra.yaml registers only 'big' but data dir contains 'bti' sstables from a newer build
// after
-- run upgradestool on source version, or upgrade Cassandra to a build supporting bti format

String fmt = nameTokens.get(2);
if (!DatabaseDescriptor.getSSTableFormats().containsKey(fmt))
    throw new IllegalStateException("Unknown sstable format in filename: " + fmt);

try { Descriptor d = Descriptor.fromFilename(file); }
catch (Throwable e) { if (e.getMessage() != null && e.getMessage().contains("unknown 'format' part")) { /* upgrade version or fix file */ } else throw e; }

When it happens

Trigger: Loading or introspecting an sstable whose filename's format token (e.g. the 'big'/'bti' slot) is not registered in DatabaseDescriptor's sstable_formats map — via Descriptor.fromFilename/componentFromFile or during startup table load.

Common situations: Restoring sstables from a newer/other Cassandra version using an experimental format (e.g. BTI) into a build without it; corrupted or hand-renamed sstable files; misconfigured sstable.format settings.

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

Appendix: source

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

                descriptors.put(cfs, onDisk);
        }
        return descriptors;
    }

    public static Component componentFromFile(File file)
    {
        String name = file.name();
        List<String> tokens = filenameTokens(name);

        return Component.parse(tokens.get(3), formatFromName(name, tokens));
    }

    private static SSTableFormat<?, ?> formatFromName(String fileName, List<String> tokens)
    {
        String formatString = tokens.get(2);
        SSTableFormat<?, ?> format = DatabaseDescriptor.getSSTableFormats().get(formatString);
        if (format == null)
            throw invalidSSTable(fileName, "unknown 'format' part (%s)", formatString);
        return format;
    }

    /**
     * Parse a sstable filename, extracting both the {@code Descriptor} and {@code Component} part.
     * The keyspace/table name will be extracted from the directory path.
     *
     * @param file the {@code File} object for the filename to parse.
     * @return a pair of the descriptor and component corresponding to the provided {@code file}.
     *
     * @throws IllegalArgumentException if the provided {@code file} does point to a valid sstable filename. This could
     * mean either that the filename doesn't look like a sstable file, or that it is for an old and unsupported
     * versions.
     */
    public static Pair<Descriptor, Component> fromFileWithComponent(File file)
    {
        return fromFileWithComponent(file, true);
    }

View on GitHub (pinned to 88fd0f6a0e)