apache/cassandra · error · ProtocolException

Invalid or unsupported protocol version (%d); supported vers

Error message

Invalid or unsupported protocol version (%d); supported versions are (%s)

What it means

ProtocolException (possibly wrapped as a silent exception) raised by ProtocolVersion.decode when the incoming frame's version number is not a supported version. It first checks historically known but now-unsupported versions so it can respond using that same old version (letting old drivers understand the error), and separately recognizes known-invalid DSE version numbers, producing a silent exception that is not logged. The message enumerates the supported versions so clients can self-correct.

Source

Thrown at src/java/org/apache/cassandra/transport/ProtocolVersion.java:118

                versions.add(version);
        return versions;
    }

    public static ProtocolVersion decode(int versionNum, boolean allowOlderProtocols)
    {
        ProtocolVersion ret = versionNum >= MIN_SUPPORTED_VERSION.num && versionNum <= MAX_SUPPORTED_VERSION.num
                              ? SUPPORTED_VERSIONS[versionNum - MIN_SUPPORTED_VERSION.num]
                              : null;

        if (ret == null)
        {
            // if this is not a supported version check the old versions
            for (ProtocolVersion version : UNSUPPORTED)
            {
                // if it is an old version that is no longer supported this ensures that we respond
                // with that same version
                if (version.num == versionNum)
                    throw new ProtocolException(ProtocolVersion.invalidVersionMessage(versionNum), version);
            }
            for (int dseVersion : KNOWN_INVALID_VERSIONS)
            {
                if (versionNum == dseVersion)
                    throw ProtocolException.toSilentException(new ProtocolException(ProtocolVersion.invalidVersionMessage(versionNum)));
            }

            // If the version is invalid reply with the channel's version
            throw new ProtocolException(invalidVersionMessage(versionNum));
        }

        if (!allowOlderProtocols && ret.isSmallerThan(CURRENT))
            throw new ProtocolException(String.format("Rejecting Protocol Version %s < %s.", ret, ProtocolVersion.CURRENT));

        return ret;
    }

    public boolean isBeta()

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Upgrade the client driver so it negotiates a supported native protocol version (see the versions listed in the error message).
Explicitly configure the driver to a supported protocolVersion (e.g. v3, v4, v5).
If forced to keep an old driver, upgrade the server to a version that still supports the legacy protocol, or proxy via a compatible shim.
Inspect the client's version byte / negotiated version config to ensure it is not 0 or a nonstandard value.

Example fix

// before: driver pinned to unsupported legacy protocol
Cluster.builder().withProtocolVersion(ProtocolVersion.V2).build();
// after: pin to a supported version
Cluster.builder().withProtocolVersion(ProtocolVersion.V4).build();

Defensive patterns

Strategy: try-catch

Validate before calling

// pick the highest version both sides advertise
ProtocolVersion v = min(highestServerSupported, highestDriverSupported);

Try / catch

try { connect(); } catch (ProtocolException e) {
  if (e.getMessage().startsWith("Invalid or unsupported protocol version")) {
    // retry with a version parsed from the supported list in the message
    connectWithVersion(parseSupportedVersions(e.getMessage()));
  }
}

Prevention

Keep drivers within a supported protocol range; upgrade very old clients (v1/v2)
Let the driver negotiate automatically rather than pinning versions
Check for DSE-vs-OSS mismatches when connecting across distributions

When it happens

Trigger: A client connects with a version byte that is neither in the SUPPORTED list nor matched to UNSUPPORTED/KNOWN_INVALID_VERSIONS handling — e.g. version 0, negative, or a too-new speculative version; or connects with a recognized-but-unsupported legacy version (v1/v2), which yields the versioned exception.

Common situations: Very old drivers speaking protocol v1/v2 against a server that dropped those versions, clients built against unreleased protocol versions, corrupted version bytes, or DSE-flavored clients hitting OSS Cassandra.

Related errors

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