apache/cassandra · error · org.apache.cassandra.transport.ProtocolException

Unknown option id

Error message

Unknown option id %d

What it means

Each data type in the native protocol has a numeric option id. DataType.fromId looks up the id in the ids table and throws this ProtocolException when no DataType is registered for it, i.e. the client sent an unrecognized type code in metadata.

Solutions

1. Align client driver version with server version so type codes match.
2. Force a mutually supported protocol version on the client.
3. Capture and inspect the frame's option id to confirm which code is being sent.
4. Regenerate/refresh prepared statement metadata if it was cached from a different server version.

Example fix

// before: hardcoded newer protocol
cluster.setProtocolVersion(ProtocolVersion.V5); // server only supports V4
// after
cluster.setProtocolVersion(ProtocolVersion.V4); // or let driver negotiate

// confirm the type code exists before sending metadata
short id = ...;
if (id >= KNOWN_TYPE_IDS.length || KNOWN_TYPE_IDS[id] == null)
    fail("Unknown data type id: " + id);

null

try { session.execute(...); } catch (ProtocolException e) {
    if (e.getMessage().startsWith("Unknown option id")) {
        // switch protocol version or upgrade driver/server
    }
}

When it happens

Trigger: A frame's type-spec section contains an unsigned short option id that does not map to any known DataType (corrupt frame, newer protocol type codes sent to an older server, or fuzzed input).

Common situations: Newer driver speaking type codes the older server doesn't know; corrupted metadata; proxies rewriting frames.

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

• e.getMessage()
• Event " + eventType.name() + " not valid for protocol…
• Invalid IP address ( . . . ) while deserializing inet…
• Invalid IP address while deserializing inet address
• Unknown opcode

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

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/DataType.java:365

                if (existingType != null)
                    throw new IllegalStateException(String.format("Duplicate option id %d", id));
                ids[id] = opt;
            }
        }

        private int getMaxId(DataType[] values)
        {
            int maxId = -1;
            for (DataType opt : values)
                maxId = Math.max(maxId, opt.getId(ProtocolVersion.CURRENT));
            return maxId;
        }

        private DataType fromId(int id)
        {
            DataType opt = ids[id];
            if (opt == null)
                throw new ProtocolException(String.format("Unknown option id %d", id));
            return opt;
        }

        public Pair<DataType, Object> decodeOne(ByteBuf body, ProtocolVersion version)
        {
            DataType opt = fromId(body.readUnsignedShort());
            Object value = opt.readValue(body, version);
            return Pair.create(opt, value);
        }

        public void writeOne(Pair<DataType, Object> option, ByteBuf dest, ProtocolVersion version)
        {
            DataType opt = option.left;
            Object obj = option.right;
            dest.writeShort(opt.getId(version));
            opt.writeValue(obj, dest, version);
        }

View on GitHub (pinned to 88fd0f6a0e)