apache/cassandra · critical · IllegalStateException

Overlapping verb ids are not allowed

Error message

Overlapping verb ids are not allowed

What it means

During the static initialization of Cassandra's internode messaging Verb registry, all NORMAL verb ids must fit below CUSTOM_VERB_START and all CUSTOM verb ids must sit at or above the minimum custom id. If the lowest custom verb id is <= the highest normal verb id (max), the two id spaces overlap and ids could be ambiguous on the wire, so startup fails with IllegalStateException.

Solutions

1. Renumber the offending custom verb id to a value strictly greater than the max NORMAL verb id (and >= CUSTOM_VERB_START).
2. Rebuild and inspect Verb.mappings / the enum declarations to confirm NORMAL and CUSTOM id ranges are disjoint.
3. If merging branches, diff Verb.java and resolve duplicate/shifted verb ids before deploying.

Example fix

// before
MAPPING_156(120, MessageCategory.MISC, custom, "CUSTOM_X") // collides with normal range
// after
MAPPING_156(3000, MessageCategory.MISC, custom, "CUSTOM_X") // inside the custom id range

// before shipping a new Verb
int id = myNewVerb.id;
assert id >= CUSTOM_VERB_START || id <= maxNormalVerbId(); // must lie inside the custom range

When it happens

Trigger: Adding a new custom Verb whose enum-declared id falls into (or below) the range occupied by NORMAL verb ids, or lowering CUSTOM_VERB_START / renumbering verbs so minCustom <= max, then booting the node (class-init of Verb).

Common situations: Contributing a patch or applying a custom messaging patch (e.g. vendor extensions) that assigns a verb id already used by core verbs; rebasing a fork across a Cassandra version where verb id ranges shifted.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Can not initialize CMS without any seeds
• Cannot find configured row cache provider class
• 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 locate . If this is a local file, please confirm…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/net/Verb.java:617

        int minCustom = Integer.MAX_VALUE;
        for (Verb v : verbs)
        {
            switch (v.kind)
            {
                case NORMAL:
                    max = Math.max(v.id, max);
                    break;
                case CUSTOM:
                    minCustom = Math.min(v.id, minCustom);
                    break;
                default:
                    throw new AssertionError("Unsupported Verb Kind: " + v.kind + " for verb " + v);
            }
        }
        minCustomId = minCustom;

        if (minCustom <= max)
            throw new IllegalStateException("Overlapping verb ids are not allowed");

        Verb[] idMap = new Verb[max + 1];
        int customCount = minCustom < Integer.MAX_VALUE ? CUSTOM_VERB_START - minCustom : 0;
        Verb[] customIdMap = new Verb[customCount + 1];
        for (Verb v : verbs)
        {
            switch (v.kind)
            {
                case NORMAL:
                    if (idMap[v.id] != null)
                        throw new IllegalArgumentException("cannot have two verbs that map to the same id: " + v + " and " + idMap[v.id]);
                    idMap[v.id] = v;
                    break;
                case CUSTOM:
                    int relativeId = idForCustomVerb(v.id);
                    if (customIdMap[relativeId] != null)
                        throw new IllegalArgumentException("cannot have two custom verbs that map to the same id: " + v + " and " + customIdMap[relativeId]);
                    customIdMap[relativeId] = v;

View on GitHub (pinned to 88fd0f6a0e)