What causes "Invalid role counter code: " in aeron-io/aeron?

Let the cluster container create and initialize the role counter; do not reuse stale counters from prior runs

aeron-io/aeron · error · IllegalStateException

Invalid role counter code

Error message

Invalid role counter code: <code>

What it means

Cluster.Role.get(long code) maps a cluster role counter value back to the Role enum; a code outside [0, ROLES.length-1] is invalid, so IllegalStateException is thrown. Indicates the role counter on the node holds a corrupt or unknown value.

Solutions

Let the cluster container create and initialize the role counter; do not reuse stale counters from prior runs
Check for negative or garbage counter values before calling Role.get
Catch IllegalStateException around Role.get and treat as node-not-started
Ensure all nodes run a compatible Aeron version

Example fix

// before
Cluster.Role role = Cluster.Role.get(roleCounter.get());
// after
long code = roleCounter.get();
Cluster.Role role = (code >= 0 && code <= 2)
    ? Cluster.Role.get(code)
    : Cluster.Role.FOLLOWER; // or handle uninitialized state

Defensive patterns

Strategy: try-catch

Validate before calling

long code = roleCounter.get();
boolean valid = code >= 0 && code <= Cluster.Role.values().length - 1;

Try / catch

try {
    Cluster.Role role = Cluster.Role.get(roleCounter.get());
} catch (IllegalStateException ex) {
    // counter uninitialized or corrupt: treat node as not started
}

Prevention

Never reuse counters from previous cluster runs
Start monitoring only after the container initializes counters
Validate counter values before mapping to Role

When it happens

Trigger: Reading the cluster's role counter (Counter) when it was never initialized, corrupted, or written by an incompatible Aeron version with more/fewer roles.

Common situations: Stale or reused counters from a previous cluster run with different counters.dat; agent/monitoring code reading a counter before the container sets it.

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

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/977fb49557613316. Report an issue: GitHub.

Appendix: source

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

         *
         * @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.
         *
         * @param code for the {@link Role}.
         * @return the {@link Role} of the cluster node.
         */
        public static Role get(final long code)
        {
            if (code < 0 || code > (ROLES.length - 1))
            {
                throw new IllegalStateException("Invalid role counter code: " + code);
            }

            return ROLES[(int)code];
        }

        /**
         * Get the role by reading the code from a counter.
         *
         * @param counter containing the value of the role.
         * @return the role for the cluster member.
         */
        public static Role get(final AtomicCounter counter)
        {
            if (counter.isClosed())
            {
                return FOLLOWER;
            }

View on GitHub (pinned to 6d60124e15)