apache/cassandra · error · IllegalArgumentException

Invalid sstable file

Error message

Invalid sstable file %s: cannot extract keyspace and table name; make sure the sstable is in the proper sub-directories

What it means

Descriptor.fromFileWithComponent requires sstable data files to live under a directory hierarchy that encodes the keyspace and table name (…/<keyspace>/<table>-<uuid>/…). If the file has no parent directory, the keyspace/table cannot be derived, so Cassandra rejects the file with this IllegalArgumentException.

Solutions

1. Place the sstable back under its proper <data_dir>/<keyspace>/<table>-<id>/ directory before using it
2. Use sstable tooling that accepts explicit keyspace/table arguments instead of path inference, or restore via a snapshot/backup that preserves directory structure
3. Re-run the tool from the original data directory rather than a moved copy

Example fix

// before
java -cp cassandra.jar …SSTableMetadataViewer /mc-1-big-Data.db
// after
java -cp cassandra.jar …SSTableMetadataViewer /var/lib/cassandra/data/ks/tbl-abc123/mc-1-big-Data.db

Path p = Paths.get(sstableFile);
if (p.getParent() == null || p.getNameCount() < 3)
    throw new IllegalArgumentException("SSTable must live under <keyspace>/<table-uuid>/ directories: " + p);

static boolean hasValidSstableLayout(File f) { return f != null && f.parent() != null && f.parent().parent() != null; }

try {
    Descriptor d = Descriptor.fromFileWithComponent(file);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("cannot extract keyspace and table name")) {
        // move file into proper <keyspace>/<table-id>/ layout and retry
    } else throw e;
}

When it happens

Trigger: Calling Descriptor.fromFileWithComponent (or sstable tools that use it) on a file placed at the filesystem root or otherwise lacking a parent directory from which keyspace/table can be parsed.

Common situations: Manually copying an sstable out of its table directory (e.g. to / or a flat temp dir) and then running sstable metadata/tools on it; scripted bulk loading that flattens the data directory structure.

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

• 3
• Exception occurred while writing to
• Failed importing SSTables
• Failed to list files in
• FSReadError (wraps IOException reading TOC file)

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

Appendix: source

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

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

        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()
    {

View on GitHub (pinned to 88fd0f6a0e)