apache/cassandra · error · IllegalArgumentException

unsupported connection type: + type

Error message

unsupported connection type: + type

What it means

OutboundConnections.connectionFor(MessageType) returns the outbound connection (small/large/urgent) matching the message size type. Any type other than SMALL/LARGE/URGENT_MESSAGES hits the default branch and throws IllegalArgumentException 'unsupported connection type: <type>'.

Solutions

1. Ensure the message type is one of SMALL_MESSAGES, LARGE_MESSAGES, or URGENT_MESSAGES before routing
2. If a new MessageType was added, add a case mapping it to an appropriate connection
3. Verify cluster nodes run compatible versions so message types deserialize identically
4. Capture the offending type value and compare it against the MessageType enum

Example fix

// before
connectionFor(type); // throws for unhandled type
// after
switch (type) {
  case SMALL_MESSAGES: return small;
  case LARGE_MESSAGES: return large;
  case URGENT_MESSAGES: return urgent;
  default: throw new IllegalStateException("type=" + type); // or map new types here
}

// guard before routing
if (type != MessageType.SMALL_MESSAGES && type != MessageType.LARGE_MESSAGES && type != MessageType.URGENT_MESSAGES)
    throw new IllegalArgumentException("cannot route type " + type);
OutboundConnections conn = connections.connectionFor(type);

try { conn = connections.connectionFor(type); } catch (IllegalArgumentException e) { conn = connections.connectionFor(MessageType.SMALL_MESSAGES); /* conservative fallback */ }

When it happens

Trigger: Routing a message whose MessageType is not one of the three size buckets — a null/corrupt type, or a new MessageType added without extending connectionFor.

Common situations: Forked/patched Cassandra adding new message types; deserialization producing an unexpected type on version-skewed clusters; internal bugs passing verification/internal types into connection routing.

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

• Unknown connection category: + category
• Attempted to serve data request from node in
• cannot have two custom verbs that map to the same id: + v +…
• cannot have two verbs that map to the same id: + v + and +…
• Cannot instantiate a non-virtual table

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

Appendix: source

Thrown at src/java/org/apache/cassandra/net/OutboundConnections.java:253

        if (msg.verb().priority == Verb.Priority.P0 || msg.header.hasFlag(MessageFlag.URGENT))
            return URGENT_MESSAGES;
        else
            return SMALL_MESSAGES;
    }

    @VisibleForTesting
    final OutboundConnection connectionFor(ConnectionType type)
    {
        switch (type)
        {
            case SMALL_MESSAGES:
                return small;
            case LARGE_MESSAGES:
                return large;
            case URGENT_MESSAGES:
                return urgent;
            default:
                throw new IllegalArgumentException("unsupported connection type: " + type);
        }
    }

    public long usingReserveBytes()
    {
        return reserveCapacity.using();
    }

    long expiredCallbacks()
    {
        return metrics.expiredCallbacks.getCount();
    }

    void incrementExpiredCallbackCount()
    {
        metrics.expiredCallbacks.mark();
    }

View on GitHub (pinned to 88fd0f6a0e)