apache/cassandra · critical · IllegalStateException

Unknown commitlog version

Error message

Unknown commitlog version 

What it means

CommitLogDescriptor.getMessagingVersion maps the commit log format version to the internal MessagingService version used when replaying mutations. If the descriptor's version is not one of the known VERSION_* constants, the switch falls through to default and throws an IllegalStateException 'Unknown commitlog version <version>'.

Source

Thrown at src/java/org/apache/cassandra/db/commitlog/CommitLogDescriptor.java:232

            throw new UnsupportedOperationException("Commitlog segment is too old to open; upgrade to 1.2.5+ first");

        return matcher;
    }

    public int getMessagingVersion()
    {
        switch (version)
        {
            case VERSION_30:
                return MessagingService.VERSION_30;
            case VERSION_40:
                return MessagingService.VERSION_40;
            case VERSION_50:
                return MessagingService.VERSION_50;
            case VERSION_60:
                return MessagingService.VERSION_60;
            default:
                throw new IllegalStateException("Unknown commitlog version " + version);
        }
    }

    public String fileName()
    {
        return FILENAME_PREFIX + version + SEPARATOR + id + FILENAME_EXTENSION;
    }

    public String cdcIndexFileName()
    {
        return FILENAME_PREFIX + version + SEPARATOR + id + INDEX_FILENAME_SUFFIX;
    }

    /**
     * Infer the corresponding cdc index file using its cdc commitlog file
     * @param cdcCommitLogSegment
     * @return cdc index file or null if the cdc index file cannot be inferred.
     */

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove or replay the segments with the Cassandra version that wrote them (usually the newest one), then downgrade cleanly.
2. Check descriptor.version in the failing segment name (it is embedded in the file name) and compare against this build's supported versions.
3. If the file is corrupted, delete it from the commitlog directory and restore from backup.
4. Upgrade this node to a release that recognizes the version constant.

Example fix

// before: 5.0-written segment replayed by a 4.0 binary -> IllegalStateException('Unknown commitlog version 50')
// after: drain/flush on the 5.0 node (nodetool drain) before downgrading, and clear commitlog_directory

String v = name.replaceAll("^CommitLog([0-9]+)-.*", "$1");
if (Integer.parseInt(v) > CommitLogDescriptor.current_version)
    logger.warn("Segment {} uses unknown version {} on this build", name, v);

try { replay(descriptor); } catch (IllegalStateException e) { logger.error("Replay failed: {}", e.getMessage()); /* drain on correct version then retry */ }

When it happens

Trigger: shouldSkipSegmentId or readMutation during commit log replay encountering a descriptor whose version field is not a recognized CommitLogDescriptor.VERSION_* value — typically a version from a newer release than this build.

Common situations: A newer-version segment slipping into replay (e.g. after a downgrade without cleaning commitlogs), corrupted header bytes producing a bogus version int, or hand-crafted/forged segment files in tests.

Related errors

• Unsupported commit log version:
• Unsupported pre-3.0 commit log found; cannot read.
• Invalid pair: '%s'
• %s property contains an item which is not in format 'keyspac
• Unknown keyspace

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