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

e.getMessage()

Error message

e.getMessage()

What it means

While mapping a serialized data type code back to a DataType, the server encountered a code it cannot resolve to a concrete type; the underlying RequestValidationException's message is rethrown as a ProtocolException. This happens during parsing of metadata (e.g. prepared-statement result metadata or UDT/collection type specs).

Solutions

1. Use a protocol version supported by both client and server (negotiate down if a type encoding is unknown).
2. Remove or re-create schema referencing custom/CUSTOM type classes that are not installed on the server.
3. Re-prepare statements after schema changes so the client receives fresh metadata.
4. Upgrade the client driver so its type-code table matches the server version.

Example fix

// before: client forces unsupported version
cluster.setProtocolVersion(ProtocolVersion.V3);
// after: let the driver negotiate
cluster = Cluster.builder().addContactPoint(host).build(); // auto-negotiation

// verify type codes used in metadata are supported by the negotiated protocol version
if (!protocolVersion.isSupportedBy(serverVersion))
    downgradeProtocol();

null

try { session.prepare(cql); } catch (ProtocolException e) {
    // re-prepare with a lower protocol version or refresh cluster metadata
    session.close(); cluster = rebuildWithLowerProtocolVersion();
}

When it happens

Trigger: A client sends type metadata (custom type name or option code) in EXECUTE/PREPARE-adjacent payloads that the server cannot resolve to a registered DataType.

Common situations: Client and server protocol-version mismatches where a type encoding differs; custom class names no longer on the server classpath (removed custom types); UDTs referencing unknown types.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unknown option id
• 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/0a0a0059b0e30de4. Report an issue: GitHub.

Appendix: source

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

                    return TypeParser.parse((String)entry.right);
                case LIST:
                    return ListType.getInstance((AbstractType)entry.right, true);
                case SET:
                    return SetType.getInstance((AbstractType)entry.right, true);
                case MAP:
                    List<AbstractType> l = (List<AbstractType>)entry.right;
                    return MapType.getInstance(l.get(0), l.get(1), true);
                case UDT:
                    return (AbstractType)entry.right;
                case TUPLE:
                    return (AbstractType)entry.right;
                default:
                    return entry.left.type;
            }
        }
        catch (RequestValidationException e)
        {
            throw new ProtocolException(e.getMessage());
        }
    }

    @VisibleForTesting
    public ProtocolVersion getProtocolVersion()
    {
        return protocolVersion;
    }

    public static final class Codec
    {
        private final DataType[] ids;

        public Codec()
        {
            DataType[] values = DataType.values();
            ids = new DataType[getMaxId(values) + 1];
            for (DataType opt : values)

View on GitHub (pinned to 88fd0f6a0e)