What causes " - code must equal ordinal value: code= " in aeron-io/aeron?

Set each Role constant's code to match its ordinal position

aeron-io/aeron · error · IllegalArgumentException

<name()> - code must equal ordinal value: code=

Error message

<name()> - code must equal ordinal value: code=<code>

What it means

Cluster.Role's constructor enforces that each role's numeric counter code equals its enum ordinal; a mismatch breaks the contract that the cluster role counter value maps directly to the enum. IllegalArgumentException is thrown at class initialization, an internal invariant of the enum definition.

Solutions

Set each Role constant's code to match its ordinal position
Do not insert role constants in the middle of the enum; append new ones
Add a test touching all Role values so the constructor check fails fast in CI

Example fix

// before
FOLLOWER(0), MEMBER(2), LEADER(1); // codes don't match ordinals
// after
FOLLOWER(0), LEADER(1), MEMBER(2);

Defensive patterns

Strategy: validation

Validate before calling

// For contributors: verify code==ordinal before editing Role
Cluster.Role[] roles = Cluster.Role.values();
for (int i = 0; i < roles.length; i++) {
    if (roles[i].name() == null) { /* unreachable; init throws otherwise */ }
}

Prevention

Only append new Role constants; never reorder
Keep explicit codes aligned with positions
Add an enum round-trip test in CI

When it happens

Trigger: Adding or reordering Cluster.Role constants while passing explicit codes that no longer match ordinal positions (e.g. inserting a new role in the middle).

Common situations: Contributors modifying the Role enum in the Aeron source and changing order or codes inconsistently; merge conflicts that reorder constants.

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 aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/35e67ba4b3646981. Report an issue: GitHub.

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/service/Cluster.java:76

        /**
         * The cluster node is a candidate to become a leader in an election.
         */
        CANDIDATE(1),

        /**
         * The cluster node is the leader for the current leadership term.
         */
        LEADER(2);

        static final Role[] ROLES = values();

        private final int code;

        Role(final int code)
        {
            if (code != ordinal())
            {
                throw new IllegalArgumentException(name() + " - code must equal ordinal value: code=" + code);
            }

            this.code = code;
        }

        /**
         * The code which matches the role in the cluster.
         *
         * @return the code which matches the role in the cluster.
         */
        public final int code()
        {
            return code;
        }

        /**
         * Get the role from a code read from a counter.
         *

View on GitHub (pinned to 6d60124e15)