apache/cassandra · error · IllegalArgumentException

Unhandled status byte: " + b

Error message

Unhandled status byte: " + b

What it means

Deserializes the AccordFastPath.Status one-byte enum. Bytes 0-2 map to NORMAL, SHUTDOWN, and UNAVAILABLE; anything else indicates a corrupted or future-version payload this build cannot interpret, so it throws IllegalArgumentException. This protects against silently accepting an unknown node status from the wire.

Solutions

1. Upgrade this node to match the peer's build so the new status byte is recognized.
2. Verify message framing/integrity if corruption is suspected.
3. Add the new status constant to this build's switch before rolling the newer nodes out.

// check the byte before full deserialization if protocol allows peeking
byte b = peekStatusByte(buffer);
if (b < 0 || b > 2) throw new IllegalArgumentException("Invalid AccordFastPath status byte: " + b);

try {
    Status status = AccordFastPath.Status.serializer.deserialize(in, version);
} catch (IllegalArgumentException e) {
    logger.error("Unparseable fast-path status payload - possible version skew", e);
    metrics.corruptPayloads.inc();
    requestResyncFromPeer();
}

When it happens

Trigger: AccordFastPath serializer deserialize() reads a status byte not in {0,1,2}, e.g. from a node running a newer build that added a status value.

Common situations: Rolling upgrades with an added Status constant; bit corruption or truncated buffers during message transport; hand-crafted test payloads using out-of-range bytes.

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

• Cannot serialize RedundantStatus larger than 0xFFFF…
• Corrupted input: expected byte 1, 2, 3, 4, 5 or 6; received
• Corrupted input: expected byte 1, 2, 3, 4 or 5; received
• Corrupted input: expected byte 1 or 2, received " + b
• Invalid queue identifier

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/accord/topology/AccordFastPath.java:88

                switch (status)
                {
                    case NORMAL: out.write(0); break;
                    case SHUTDOWN: out.write(1); break;
                    case UNAVAILABLE: out.write(2); break;
                    default: throw new IllegalStateException("Unhandled status: " + this);
                }
            }

            @Override
            public Status deserialize(DataInputPlus in, Version version) throws IOException
            {
                byte b = in.readByte();
                switch (b)
                {
                    case 0: return NORMAL;
                    case 1: return SHUTDOWN;
                    case 2: return UNAVAILABLE;
                    default: throw new IllegalArgumentException("Unhandled status byte: " + b);
                }
            }

            @Override
            public long serializedSize(Status status, Version version)
            {
                return TypeSizes.BYTE_SIZE;
            }
        };
    };

    public static class NodeInfo
    {
        public final Status status;
        public final long updated;

        public NodeInfo(Status status, long updated)
        {

View on GitHub (pinned to 88fd0f6a0e)