apache/cassandra · error · IllegalStateException

Illegal state:

Error message

Illegal state: 

What it means

This is the default arm of the same switch in Commit.checkCMSState (Commit.java:426): when the CMS state supplier returns a value that is neither LOCAL, REMOTE, nor GOSSIP, the code throws IllegalStateException("Illegal state: " + state). It is a defensive invariant guard against an unknown/uninitialized ClusterMetadataService state, meaning the node's cluster-metadata mode is not one of the recognized values.

Source

Thrown at src/java/org/apache/cassandra/tcm/Commit.java:426

            messagingService.accept(message.responseWith(result), message.from());
        }

        private void checkCMSState()
        {
            switch (cmsStateSupplier.get())
            {
                case RESET:
                case LOCAL:
                    break;
                case REMOTE:
                    throw new NotCMSException("Not currently a member of the CMS, can't commit");
                case GOSSIP:
                    String msg = "Tried to commit when in gossip mode";
                    logger.error(msg);
                    throw new IllegalStateException(msg);
                default:
                    throw new IllegalStateException("Illegal state: " + cmsStateSupplier.get());
            }
        }
    }

    public interface Replicator
    {
        Replicator NO_OP = (a,b) -> {};
        void send(Result result, InetAddressAndPort source);
    }

    public static class DefaultReplicator implements Replicator
    {
        public static class RoutingHelper
        {
            private final Directory directory;
            private final EndpointLookup endpoints;

            public RoutingHelper(ClusterMetadata metadata)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Log/inspect the reported state value to see which unexpected CMSState was returned and why the state supplier resolved to it.
2. Ensure the node has fully initialized ClusterMetadataService before participating in TCM commits (gate doVerb on service initialization).
3. If running a mixed-version cluster, verify the peer's TCM state enum is compatible with this node's version.
4. Restart the affected node to reinitialize the CMS state if it is stuck in an unknown value.

ClusterMetadataService.CMSState s = ClusterMetadataService.instance().state();
if (s != CMSState.LOCAL && s != CMSState.REMOTE && s != CMSState.GOSSIP)
    logger.warn("CMS state {} unrecognized; delaying commit", s);

try { checkCMSState(); } catch (IllegalStateException e) { logger.error("Unexpected CMS state during commit", e); /* defer or abort the commit */ }

When it happens

Trigger: Commit.doVerb invokes checkCMSState and cmsStateSupplier.get() returns an enum value outside LOCAL/REMOTE/GOSSIP — e.g. an uninitialized or transiently null/unknown CMS state during startup or a future state added without updating the switch.

Common situations: Node startup race where cluster metadata service state is not yet resolved when a commit verb arrives; custom builds or newer protocol versions introducing an extra CMS state; corrupted in-memory CMS state.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Tried to commit when in gossip mode
• Node %s is not a CMS member in epoch %s; members=%s
• Can only initialize cluster identifier during epoch %d, but
• Failed to find first CMS node in directory
• Initial CMS node needs to be fully joined, not: %s

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