apache/cassandra · error · IllegalArgumentException

Invalid sstable file

Error message

Invalid sstable file ${name}: ${msgFormat}

What it means

invalidSSTable() is Descriptor's central helper that raises IllegalArgumentException with 'Invalid sstable file <name>: <reason>' for every structural validation failure beyond version parsing — e.g. keyspace/table cannot be extracted, wrong sub-directory layout, or bad generation/component fields. Callers include formatFromName, fromFileWithComponent, validateAndExtractInfo, and parentOf.

Solutions

1. Move the SSTable into the correct per-table subdirectory (data/<keyspace>/<table>-<uuid>/) as the error hint about sub-directories suggests
2. Regenerate the descriptor path via the node/tooling instead of hand-assembling paths
3. If the file is unrelated to this table, relocate or delete it; verify keyspace/table extraction by matching the directory names

Example fix

// before
/var/lib/cassandra/data/ks/ks-t1-00001-Data.db   (flat layout)
// after
/var/lib/cassandra/data/ks/t1-<table-uuid>/t1-00001-Data.db

File tableDir = file.getParentFile();
if (tableDir == null || !tableDir.getName().matches(".+-[0-9a-fA-F-]{36}"))
    throw new IllegalArgumentException("SSTable not in a per-table subdirectory: " + file);

try { Descriptor d = Descriptor.parentOf(file); }
catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid sstable file"))
        // move the file into data/<ks>/<table>-<uuid>/
}

When it happens

Trigger: Constructing a Descriptor from a file or path (Descriptor.fromFilename, fromFileWithComponent, parentOf) where the file is outside the expected per-table subdirectories, or the name cannot yield keyspace/table/gen/component — e.g. running tools against flat (pre-3.0-style) directories.

Common situations: Running nodetool/sstable tools in the wrong directory; moving SSTables to a different table directory without the matching table UUID; misconfigured backups restored into wrong locations.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 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/b4e95a4206555c9e. Report an issue: GitHub.

Appendix: source

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

        SSTableInfo(Version version, SSTableId id, Component component)
        {
            this.version = version;
            this.id = id;
            this.component = component;
        }
    }

    private static File parentOf(String name, File file)
    {
        File parent = file.parent();
        if (parent == null)
            throw invalidSSTable(name, "cannot extract keyspace and table name; make sure the sstable is in the proper sub-directories");
        return parent;
    }

    private static IllegalArgumentException invalidSSTable(String name, String msgFormat, Object... parameters)
    {
        throw new IllegalArgumentException(String.format("Invalid sstable file " + name + ": " + msgFormat, parameters));
    }

    public IMetadataSerializer getMetadataSerializer()
    {
        return new MetadataSerializer();
    }

    /**
     * @return true if the current Cassandra version can read the given sstable version
     */
    public boolean isCompatible()
    {
        return version.isCompatible();
    }

    public Set<Component> discoverComponents()
    {
        Set<Component> components = Sets.newHashSetWithExpectedSize(Component.Type.all.size());

View on GitHub (pinned to 88fd0f6a0e)