{"record":{"id":"67f9612308234883","repo":"apache/cassandra","slug":"invalid-sstable-file-name-unknown-format-par","errorCode":null,"errorMessage":"Invalid sstable file ${name}: unknown 'format' part (%s)","messagePattern":"Invalid sstable file (.+?): unknown 'format' part \\((.+?)\\)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/io/sstable/Descriptor.java","lineNumber":311,"sourceCode":"                descriptors.put(cfs, onDisk);\n        }\n        return descriptors;\n    }\n\n    public static Component componentFromFile(File file)\n    {\n        String name = file.name();\n        List<String> tokens = filenameTokens(name);\n\n        return Component.parse(tokens.get(3), formatFromName(name, tokens));\n    }\n\n    private static SSTableFormat<?, ?> formatFromName(String fileName, List<String> tokens)\n    {\n        String formatString = tokens.get(2);\n        SSTableFormat<?, ?> format = DatabaseDescriptor.getSSTableFormats().get(formatString);\n        if (format == null)\n            throw invalidSSTable(fileName, \"unknown 'format' part (%s)\", formatString);\n        return format;\n    }\n\n    /**\n     * Parse a sstable filename, extracting both the {@code Descriptor} and {@code Component} part.\n     * The keyspace/table name will be extracted from the directory path.\n     *\n     * @param file the {@code File} object for the filename to parse.\n     * @return a pair of the descriptor and component corresponding to the provided {@code file}.\n     *\n     * @throws IllegalArgumentException if the provided {@code file} does point to a valid sstable filename. This could\n     * mean either that the filename doesn't look like a sstable file, or that it is for an old and unsupported\n     * versions.\n     */\n    public static Pair<Descriptor, Component> fromFileWithComponent(File file)\n    {\n        return fromFileWithComponent(file, true);\n    }","sourceCodeStart":293,"sourceCodeEnd":329,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/sstable/Descriptor.java#L293-L329","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a Cassandra build that supports the format named in the file (upgrade if files use bti/experimental formats).","Fix the filename if it was manually renamed and the format token is wrong.","Check DatabaseDescriptor.getSSTableFormats() (cassandra.yaml sstable_formats config) to confirm the format is registered/enabled.","If files are unneeded/corrupt, remove or regenerate them with SSTableWriter on the target version."],"exampleFix":"// before\n// cassandra.yaml registers only 'big' but data dir contains 'bti' sstables from a newer build\n// after\n-- run upgradestool on source version, or upgrade Cassandra to a build supporting bti format","handlingStrategy":"try-catch","validationCode":"String fmt = nameTokens.get(2);\nif (!DatabaseDescriptor.getSSTableFormats().containsKey(fmt))\n    throw new IllegalStateException(\"Unknown sstable format in filename: \" + fmt);","typeGuard":null,"tryCatchPattern":"try { Descriptor d = Descriptor.fromFilename(file); }\ncatch (Throwable e) { if (e.getMessage() != null && e.getMessage().contains(\"unknown 'format' part\")) { /* upgrade version or fix file */ } else throw e; }","preventionTips":["Keep source and target Cassandra versions compatible when restoring sstables.","Run upgradestool before moving sstables to older builds.","Never hand-edit sstable filenames; preserve all name tokens.","Confirm sstable format registration in cassandra.yaml for custom formats."],"tags":["sstable","descriptor","filename-parsing","format"],"backgroundTag":"invalid-identifier-format","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}