apache/cassandra · error · IllegalStateException

Bad node state: {nodeState}

Error message

Bad node state: {nodeState}

What it means

StorageService.operationMode() maps the internal node state enum to the externally visible Mode. If the internal state has no mapping (an internal invariant violation, e.g. a new enum value added without updating this switch), it throws IllegalStateException to fail fast rather than return a bogus mode. This is a defensive 'should never happen' guard, not a user-caused condition.

Source

Thrown at src/java/org/apache/cassandra/service/StorageService.java:3812

        NodeState nodeState = ClusterMetadata.current().myNodeState();
        switch (nodeState)
        {
            case REGISTERED:
                return Mode.STARTING;
            case BOOT_REPLACING:
            case BOOTSTRAPPING:
                return Mode.JOINING;
            case JOINED:
                return NORMAL;
            case LEAVING:
                return Mode.LEAVING;
            case LEFT:
                return Mode.DECOMMISSIONED;
            case MOVING:
                return Mode.MOVING;
        }
        throw new IllegalStateException("Bad node state: " + nodeState);
    }

    public boolean isStarting()
    {
        return operationMode() == Mode.STARTING;
    }

    public boolean isMoving()
    {
        return operationMode() == Mode.MOVING;
    }

    public boolean isJoining()
    {
        return operationMode() == Mode.JOINING;
    }

    public boolean isDrained()

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Restart the node; transient uninitialize states usually clear
2. Upgrade Cassandra to a version where all node states are mapped
3. Check for patched/modified code that added a new node state enum value without updating the mapping switch
4. Report a bug with full node logs - this indicates an internal invariant violation

String mode = storageService.getOperationMode(); // inspect instead of assuming
if (mode == null || mode.isEmpty()) { /* node in unexpected state */ }

try { operationMode(); } catch (IllegalStateException e) { log.error("node state enum unmapped - upgrade/patch bug", e); restartNode(); }

When it happens

Trigger: Calling operationMode() (directly or via isStarting()/jmx getOperationMode) when the node's internal state enum value is not handled by the switch in getOperationMode().

Common situations: Custom patches or forks adding new node states; running a partially upgraded/mixed-version cluster where a newer state value is seen; corrupted in-memory state during startup races.

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

• No holder claimed
• No holder claimed isPendingRepair: %s, isPendingRepair %s
• Insufficient read responses: ${readResponses}; need ${sizeOf
• All values must be either negative or positive, got %d month
• Invalid number of components, expecting %d but got %d

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