apache/cassandra · error · ProtocolException

Unknown code %d for a consistency level

Error message

Unknown code %d for a consistency level

What it means

Thrown by ConsistencyLevel.fromCode when a wire-protocol consistency level code is outside the valid range [0, codeIdx.length). The native protocol encodes consistency levels as shorts and this maps them back to enum values. It means the client sent an unrecognized consistency code.

Source

Thrown at src/java/org/apache/cassandra/db/ConsistencyLevel.java:87

            codeIdx[cl.code] = cl;
        }
    }

    ConsistencyLevel(int code)
    {
        this(code, false);
    }

    ConsistencyLevel(int code, boolean isDCLocal)
    {
        this.code = code;
        this.isDCLocal = isDCLocal;
    }

    public static ConsistencyLevel fromCode(int code)
    {
        if (code < 0 || code >= codeIdx.length)
            throw new ProtocolException(String.format("Unknown code %d for a consistency level", code));
        return codeIdx[code];
    }

    public static ConsistencyLevel fromString(String str)
    {
        return valueOf(toUpperCaseLocalized(str));
    }

    public static int quorumFor(AbstractReplicationStrategy replicationStrategy)
    {
        return (replicationStrategy.getReplicationFactor().allReplicas / 2) + 1;
    }

    public static int localQuorumFor(AbstractReplicationStrategy replicationStrategy, String dc)
    {
        return (replicationStrategy instanceof NetworkTopologyStrategy)
             ? (((NetworkTopologyStrategy) replicationStrategy).getReplicationFactor(dc).allReplicas / 2) + 1
             : quorumFor(replicationStrategy);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Upgrade the client driver to a version compatible with the server's protocol version.
2. Check for intermediaries (proxies, LBs with protocol awareness) mangling frames; disable or upgrade them.
3. Pin a supported protocol version in the driver config (e.g. protocolVersion: v4) to avoid negotiation issues.
4. Inspect server logs for the offending client and reproduce with a known-good driver.

Example fix

// before: driver negotiating an unsupported protocol version
Cluster.builder().addContactPoint(host).build();
// after
Cluster.builder().addContactPoint(host)
       .withProtocolVersion(ProtocolVersion.V4)
       .build();

// Java driver client-side guard
if (code < 0 || code > 13) throw new IllegalArgumentException("invalid consistency code " + code);

catch (ProtocolException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unknown code")) {
        // downgrade protocol version or upgrade driver
        reconnectWithLowerProtocolVersion();
    } else throw e;
}

When it happens

Trigger: A CQL native protocol request whose consistency-level field is negative or exceeds the highest defined enum code, e.g. a driver bug or a hand-rolled protocol client.

Common situations: Custom or old driver versions speaking a mismatched protocol version; proxy/middleware rewriting frames incorrectly; fuzzing or malformed client traffic.

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

• native_transport_max_frame_size must be positive value < %dB
• Invalid value for progress_barrier_min_consistency_level %s.
• Invalid value for.progress_barrier_default_consistency_level
• ANY ConsistencyLevel is only supported for writes
• You must use conditional updates for serializable writes

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