apache/cassandra · error · IORuntimeException

Unhandled record type

Error message

Unhandled record type: ${type}

What it means

FQLQueryReader.readMarshallable deserializes a full-query-log record from a Chronicle Wire binary log. After reading the record's type field it switches on a numeric record type code; if the code matches none of the known cases it throws this IORuntimeException. This guards the reader against log records written in a format it does not understand.

Solutions

1. Upgrade the fqltool / Cassandra version to one matching the version that wrote the log file
2. Verify the file is a genuine full-query-log produced by BinLog/FullQueryLogger
3. Check for file corruption or truncation and re-capture the query log

Example fix

// before: replaying a log from a newer Cassandra
fqltool replay --log_path /var/log/cassandra/dump.bin ...
// after: upgrade fqltool to match the writer version, or re-capture with the current version

File logFile = new File(path);
if (!logFile.isFile() || logFile.length() == 0) throw new IllegalArgumentException("not a FQL log: " + path);

try { reader.readMarshallable(wireIn); } catch (IORuntimeException e) { if (e.getMessage().startsWith("Unhandled record type")) { skipRecord(); } else throw e; }

When it happens

Trigger: Calling readMarshallable (directly or via Chronicle Wire when reading a binlog file) on a record whose numeric type code does not match any handled case in the switch.

Common situations: Replaying a log file produced by a newer Cassandra version that introduced a new record type; corrupt or truncated log data misaligning the type field; pointing the replayer at a file that is not a full query log.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Corrupted input: expected byte 1, 2, 3, 4, 5 or 6; received
• Corrupted input: expected byte 1, 2, 3, 4 or 5; received
• Expected instance of
• Invalid 16-bits integer value, expecting 2 bytes but got
• Invalid 32-bits float value, expecting 4 bytes but got

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

Appendix: source

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

                    int numSubValues = in.int32();
                    for (int zz = 0; zz < numSubValues; zz++)
                    {
                        byte[] valueBytes = in.bytes();
                        subValues.add(valueBytes == null ? null : ByteBuffer.wrap(valueBytes));
                    }
                }
                query = new FQLQuery.Batch(keyspace,
                                           protocolVersion,
                                           queryOptions,
                                           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))

View on GitHub (pinned to 88fd0f6a0e)