apache/cassandra · error · IORuntimeException

Unsupported record version

Error message

Unsupported record version [${version}] - highest supported version is [${CURRENT_VERSION}]

What it means

FQLQueryReader.verifyVersion reads a 16-bit version number from the record header and rejects it if it exceeds CURRENT_VERSION, the highest format version this reader understands. The full-query-log format is versioned; older readers cannot safely parse records written by newer writers.

Solutions

Upgrade fqltool/Cassandra so CURRENT_VERSION is at least the log's version
Re-capture the query log with the current tool version
Inspect the log's version field with fqltool dump to confirm the mismatch

Defensive patterns

Strategy: validation

Validate before calling

// peek the version before full parsing, mirroring verifyVersion
int version = readVersionField(logFile);
if (version > CURRENT_VERSION) throw new UnsupportedOperationException("log version " + version + " newer than supported " + CURRENT_VERSION);

Try / catch

try { replay(log); } catch (IORuntimeException e) { if (e.getMessage().contains("Unsupported record version")) { log.error("Upgrade fqltool to read this log"); } else throw e; }

Prevention

Upgrade the tool before replaying logs from upgraded clusters
Version-stamp and archive logs with the Cassandra version that wrote them
Test cross-version log reads in mixed-version staging

When it happens

Trigger: Reading a record (via readMarshallable) whose VERSION field is greater than FQLQueryReader.CURRENT_VERSION, e.g. a log written by a newer Cassandra release.

Common situations: Upgrading Cassandra to a release that bumped the binlog format version, then replaying those logs with an older fqltool build; mixed-version clusters sharing log files.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at tools/fqltool/src/org/apache/cassandra/fqltool/FQLQueryReader.java:126

                                           queryStartTime,
                                           generatedTimestamp,
                                           generatedNowInSeconds,
                                           batchType,
                                           queries,
                                           values);
                break;
            default:
                throw new IORuntimeException("Unhandled record type: " + type);
        }
    }

    private void verifyVersion(WireIn wireIn)
    {
        int version = wireIn.read(VERSION).int16();

        if (version > CURRENT_VERSION)
        {
            throw new IORuntimeException("Unsupported record version [" + version
                                         + "] - highest supported version is [" + CURRENT_VERSION + ']');
        }
    }

    private String readType(WireIn wireIn) throws IORuntimeException
    {
        String type = wireIn.read(TYPE).text();
        if (!SINGLE_QUERY.equals(type) && !BATCH.equals(type))
        {
            throw new IORuntimeException("Unsupported record type field [" + type
                                         + "] - supported record types are [" + SINGLE_QUERY + ", " + BATCH + ']');
        }

        return type;
    }

    public FQLQuery getQuery()
    {

View on GitHub (pinned to 88fd0f6a0e)