apache/cassandra · error · IllegalArgumentException

Invalid type id

Error message

Invalid type id: %d

What it means

StreamMessage.Type assigns an integer id to each streaming message type; lookupById resolves ids received off the wire back to a Type. IllegalArgumentException means the peer sent a message-type id this node's idToTypeMap does not know — almost always a protocol/version mismatch between nodes or corrupted stream data.

Solutions

1. Bring all cluster nodes to the same Cassandra version (complete rolling upgrade) and retry streaming
2. Verify messagingVersion negotiation between the two nodes; check cassandra versions with nodetool version on both ends
3. If corruption is suspected, check network health and restart the stream session; inspect the raw id in the log against known Type ids
4. If seen in tests after adding a new StreamMessage.Type, ensure the new type is registered in the static idToTypeMap on both sides

int id = input.readInt();
if (StreamMessage.Type.idToTypeMap.get(id) == null) throw new IOException("peer sent unknown stream type " + id + "; version mismatch?");

try { Type t = StreamMessage.Type.lookupById(id); }
catch (IllegalArgumentException e) {
    throw new IOException("stream protocol mismatch (id=" + id + "); check node versions", e);
}

When it happens

Trigger: deserialize() reads a type id from the wire and calls Type.lookupById(id); the id is not registered — nodes running different Cassandra versions where one knows message types the other does not, or byte corruption/misframing of the stream protocol.

Common situations: Rolling upgrades/downgrades across versions with streaming protocol changes; mixing nodes from incompatible branches in a test cluster; deserializing garbage after a framing offset bug (e.g. following an earlier malformed message).

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

• A node required to move the data consistently is down
• Can not start range streaming as all candidates
• Can't join the ring because bootstrap hasn't completed.
• Cannot send stream data messages for preview streaming…
• CF was dropped during streaming

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

Appendix: source

Thrown at src/java/org/apache/cassandra/streaming/messages/StreamMessage.java:90

        STREAM_INIT    (10, 5, StreamInitMessage.serializer   );

        private static final Map<Integer, Type> idToTypeMap;

        static
        {
            idToTypeMap = new HashMap<>();
            for (Type t : values())
            {
                if (idToTypeMap.put(t.id, t) != null)
                    throw new RuntimeException("Two StreamMessage Types map to the same id: " + t.id);
            }
        }

        public static Type lookupById(int id)
        {
            Type t = idToTypeMap.get(id);
            if (t == null)
                throw new IllegalArgumentException("Invalid type id: " + id);

            return t;
        }

        public final int id;
        public final int priority;

        public final Serializer<StreamMessage> inSerializer;
        public final Serializer<StreamMessage> outSerializer;

        Type(int id, int priority, Serializer serializer)
        {
            this(id, priority, serializer, serializer);
        }

        @SuppressWarnings("unchecked")
        Type(int id, int priority, Serializer inSerializer, Serializer outSerializer)
        {

View on GitHub (pinned to 88fd0f6a0e)