apache/cassandra · critical · IllegalArgumentException

cannot have two custom verbs that map to the same id: + v +…

Error message

cannot have two custom verbs that map to the same id: + v + and + customIdMap[relativeId]

What it means

Custom verbs are mapped to a dense relative-id table (customIdMap) computed via idForCustomVerb. If two CUSTOM verbs resolve to the same relative id, the lookup table would overwrite one with the other, so initialization throws IllegalArgumentException.

Solutions

Assign a unique id to one of the two colliding custom verbs, above CUSTOM_VERB_START.
If using plugins/extensions, allocate custom verb id ranges per plugin to avoid collisions.
Check idForCustomVerb to understand the relative-id computation if ids look unique but still collide.

Example fix

// before
CUSTOM_VERB(5001, "MY_REFRESH")
CUSTOM_VERB(5001, "MY_RELOAD")
// after
CUSTOM_VERB(5001, "MY_REFRESH")
CUSTOM_VERB(5002, "MY_RELOAD")

Defensive patterns

Strategy: validation

Validate before calling

Set<Integer> seen = new HashSet<>();
for (Verb v : Verb.values())
    if (v.kind == Kind.CUSTOM) assertTrue(seen.add(Verb.idForCustomVerb(v.id)), "dup custom verb " + v);

Prevention

Assign disjoint custom-verb id ranges per patch/plugin
Run Verb class-init in a smoke test before cluster rollout
Document allocated custom ids in the fork's README

When it happens

Trigger: Registering two CUSTOM Verbs with identical ids (or ids that collapse to the same relative id), triggering Verb class static init.

Common situations: Multiple vendor/plugin patches each adding custom verbs with the same hardcoded id; copy-pasting a custom verb declaration without bumping the id.

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

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

Appendix: source

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

        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;
                    break;
                default:
                    throw new AssertionError("Unsupported Verb Kind: " + v.kind + " for verb " + v);
            }
        }

        idToVerbMap = idMap;
        idToCustomVerbMap = customIdMap;
    }

    public static Verb fromId(int id)
    {
        Verb[] verbs = idToVerbMap;
        if (id >= minCustomId)
        {
            id = idForCustomVerb(id);
            verbs = idToCustomVerbMap;

View on GitHub (pinned to 88fd0f6a0e)