apache/cassandra · error · ProtocolException

Unknown error code

Error message

Unknown error code %d

What it means

ExceptionCode.fromValue maps numeric protocol error codes to the ExceptionCode enum. Unknown integers (not present in the wire protocol) raise a ProtocolException. This guards the native-protocol error parsing against unrecognized or corrupt values.

Solutions

1. Upgrade the driver/library to a version that knows the error code
2. Force a matching protocol version on both client and server (e.g. protocol_version setting)
3. Log and inspect the raw frame to identify the unexpected code
4. If intercepting exceptions, fall back to UNKNOWN handling instead of crashing

Example fix

// before
ExceptionCode code = ExceptionCode.fromValue(0x1234); // ProtocolException
// after
try {
    ExceptionCode code = ExceptionCode.fromValue(raw);
} catch (ProtocolException e) {
    logger.warn("Unknown error code " + raw + "; treating as UNKNOWN");
    code = ExceptionCode.UNKNOWN;
}

// check the code is in the known set before mapping
boolean known = Arrays.stream(ExceptionCode.values()).anyMatch(c -> c.rawValue == rawValue);

try {
    code = ExceptionCode.fromValue(value);
} catch (ProtocolException e) {
    logger.warn("Unknown error code " + value + ", falling back to UNKNOWN");
    code = ExceptionCode.UNKNOWN;
}

When it happens

Trigger: Deserializing a native protocol ERROR response whose int code has no ExceptionCode mapping (e.g. a code from a newer/older protocol version the driver doesn't know).

Common situations: Driver/server protocol version mismatch; corrupted or malicious frames; writing a custom server sending nonstandard error codes; forward-compatibility issues after upgrades.

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

• Invalid BATCH message type
• Invalid IP address ( . . . ) while deserializing inet…
• Invalid IP address while deserializing inet address
• Invalid query kind in BATCH messages. Must be 0 or 1 but…
• Invalid value for the paging state

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

Appendix: source

Thrown at src/java/org/apache/cassandra/exceptions/ExceptionCode.java:77

    public final int value;
    private static final Map<Integer, ExceptionCode> valueToCode = new HashMap<>(ExceptionCode.values().length);
    static
    {
        for (ExceptionCode code : ExceptionCode.values())
            valueToCode.put(code.value, code);
    }

    ExceptionCode(int value)
    {
        this.value = value;
    }

    public static ExceptionCode fromValue(int value)
    {
        ExceptionCode code = valueToCode.get(value);
        if (code == null)
            throw new ProtocolException(String.format("Unknown error code %d", value));
        return code;
    }
}

View on GitHub (pinned to 88fd0f6a0e)