apache/cassandra · critical · IllegalStateException

Unknown compression

Error message

Unknown compression

What it means

When restoring an archived commit log segment, the descriptor read from its header can specify a compressor (e.g. LZ4, Snappy). CommitLogArchiver calls CompressionParams.createCompressor to instantiate it; if the class name cannot be resolved or configured, the ConfigurationException is wrapped in an IllegalStateException with message 'Unknown compression'. The segment cannot be replayed without the compressor.

Source

Thrown at src/java/org/apache/cassandra/db/commitlog/CommitLogArchiver.java:309

                    throw new IllegalStateException(String.format("Cannot safely construct descriptor for segment, as name and header descriptors do not match (%s vs %s): %s", fromHeader, fromName, fromFile.path()));
                else if (fromName != null && fromHeader == null)
                    throw new IllegalStateException("Cannot safely construct descriptor for segment, as name descriptor implies a version that should contain a header descriptor, but that descriptor could not be read: " + fromFile.path());
                else if (fromHeader != null)
                    descriptor = fromHeader;
                else descriptor = fromName;

                if (descriptor.version > CommitLogDescriptor.current_version)
                    throw new IllegalStateException("Unsupported commit log version: " + descriptor.version);

                if (descriptor.compression != null)
                {
                    try
                    {
                        CompressionParams.createCompressor(descriptor.compression);
                    }
                    catch (ConfigurationException e)
                    {
                        throw new IllegalStateException("Unknown compression", e);
                    }
                }

                File toFile = new File(DatabaseDescriptor.getCommitLogLocation(), descriptor.fileName());
                if (toFile.exists())
                {
                    if (logger.isTraceEnabled())
                        logger.trace("Skipping restore of archive {} as the segment already exists in the restore location {}",
                                     fromFile.path(), toFile.path());
                    continue;
                }

                String command = FROM.matcher(restoreCommand).replaceAll(Matcher.quoteReplacement(fromFile.path()));
                command = TO.matcher(command).replaceAll(Matcher.quoteReplacement(toFile.path()));
                try
                {
                    exec(command);
                }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Install/restore the compressor library (and class) that the segment header names so createCompressor succeeds.
2. Confirm the archive came from a stock Cassandra build; custom codecs are not portable across installations.
3. Skip/exclude the affected segment from the restore and replay from another archive or accept the data loss for that segment.
4. Upgrade to a Cassandra version where the codec name used by the source cluster exists.

Example fix

// before: archive uses compressor 'Compressor7' not present on this node -> IllegalStateException('Unknown compression')
// after: restore original segment from a node using a supported codec, or add the codec's jar to the classpath before restart

CommitLogDescriptor d = CommitLogDescriptor.fromFileName(segment.getName());
if (d != null && d.compression != null) {
    try { CompressionParams.createCompressor(d.compression); }
    catch (ConfigurationException e) { logger.error("Missing compressor {} for {}", d.compression, segment); }
}

try { archiver.maybeRestoreArchive(); } catch (IllegalStateException e) { logger.error("Cannot restore segment: {}", e.getMessage()); }

When it happens

Trigger: maybeRestoreArchive reads a segment descriptor whose header carries a compression parameters string naming a compressor class that is not on the classpath or is misspelled/renamed, so CompressionParams.createCompressor throws ConfigurationException.

Common situations: Restoring archives written by a build with a custom/patched compression codec, classpath missing the codec library after an upgrade, or manually edited compression settings in the descriptor-carrying segment.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• commitlog_disk_access_mode =
• Unable to list directory
• Cannot safely construct descriptor for segment, either from
• Cannot safely construct descriptor for segment, as name and
• Cannot safely construct descriptor for segment, as name desc

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