apache/cassandra · error · IllegalArgumentException

Unknown connection category: + category

Error message

Unknown connection category: + category

What it means

OutboundConnectionSettings.tcpUserTimeoutInMS() maps a ConnectionCategory to its yaml-configured TCP user timeout. If the category is neither MESSAGING nor STREAMING, it throws IllegalArgumentException 'Unknown connection category: <category>'.

Solutions

1. Add a case for the missing ConnectionCategory (or fall back to the MESSAGING timeout) in tcpUserTimeoutInMS()
2. Check which category the failing connection uses and configure its timeout via the correct yaml property
3. If this fires with stock enum values, treat it as an internal bug and report with the stack trace
4. Write an exhaustive-switch test iterating ConnectionCategory.values()

Example fix

// before
default: throw new IllegalArgumentException("Unknown connection category: " + category);
// after
case URGENT_MESSAGES: return DatabaseDescriptor.getInternodeTcpUserTimeoutInMS();
default: throw new IllegalArgumentException("Unknown connection category: " + category);

// before computing timeout for a connection
if (category != ConnectionCategory.MESSAGING && category != ConnectionCategory.STREAMING)
    throw new IllegalArgumentException("tcpUserTimeout not configurable for " + category);

try { int t = settings.tcpUserTimeoutInMS(); } catch (IllegalArgumentException e) { int t = DatabaseDescriptor.getInternodeTcpUserTimeoutInMS(); /* safe default */ }

When it happens

Trigger: withDefaults() (or direct callers) computing the TCP user timeout for a connection whose ConnectionCategory falls through the switch — an unexpected or newly added enum value reached this settings path.

Common situations: New ConnectionCategory values (e.g. internal URGENT_MESSAGES) added without updating this switch; custom patches passing unsupported categories into settings builders.

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

• denylist_max_keys_per_table must be a positive integer.
• denylist_max_keys_total must be a positive integer.
• does not match
• internode_max_message_size must no exceed…
• internode_max_message_size must no exceed…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/net/OutboundConnectionSettings.java:414

    }

    public int tcpConnectTimeoutInMS()
    {
        return tcpConnectTimeoutInMS != null ? tcpConnectTimeoutInMS
                                             : DatabaseDescriptor.getInternodeTcpConnectTimeoutInMS();
    }

    public int tcpUserTimeoutInMS(ConnectionCategory category)
    {
        // Reusing tcpUserTimeoutInMS for both messaging and streaming, since the connection is created for either one of them.
        if (tcpUserTimeoutInMS != null)
            return tcpUserTimeoutInMS;

        switch (category)
        {
            case MESSAGING: return DatabaseDescriptor.getInternodeTcpUserTimeoutInMS();
            case STREAMING: return DatabaseDescriptor.getInternodeStreamingTcpUserTimeoutInMS();
            default: throw new IllegalArgumentException("Unknown connection category: " + category);
        }
    }

    public boolean tcpNoDelay()
    {
        if (tcpNoDelay != null)
            return tcpNoDelay;

        if (DatabaseDescriptor.isClientOrToolInitialized() || isInLocalDC(getBroadcastAddressAndPort(), to))
            return INTRADC_TCP_NODELAY;

        return DatabaseDescriptor.getInterDCTcpNoDelay();
    }

    public AcceptVersions acceptVersions(ConnectionCategory category)
    {
        return acceptVersions != null ? acceptVersions
                                      : category.isStreaming()

View on GitHub (pinned to 88fd0f6a0e)