aeron-io/aeron · error · ClusterException

invalid election state counter code

Error message

invalid election state counter code: ${code}

What it means

ElectionState.get(long) maps the integer value stored in the election state counter back to an ElectionState enum. The counter must hold a code between 0 and STATES.length-1; any other value cannot correspond to a valid election state, so a ClusterException is thrown.

Solutions

1. Validate the counter value is 0..ElectionState.STATES.length-1 before calling get
2. Check that the election state counter was properly initialized/allocated before being read
3. Guard against reading a closed counter (counter.isClosed()) and treat that as 'no election running'
4. If you wrote the value yourself, fix the constant used to set the counter

Example fix

// before
ElectionState state = ElectionState.get(counter.get());
// after
long code = counter.isClosed() ? -1 : counter.get();
ElectionState state = (code >= 0 && code < ElectionState.values().length)
    ? ElectionState.get(code)
    : ElectionState.INIT;

long code = counter.isClosed() ? -1 : counter.get(); if (code < 0 || code >= ElectionState.values().length) return null;

boolean isValidElectionCode(long c) { return c >= 0 && c < ElectionState.values().length; }

try { state = ElectionState.get(code); } catch (ClusterException e) { state = ElectionState.INIT; }

When it happens

Trigger: Calling ElectionState.get with a raw counter value outside the valid range — typically when reading the election state counter after corruption, or passing a sentinel/negative value (e.g. NULL_VALUE) read from an uninitialized or reset counter.

Common situations: Reading the election counter before the election is initialized, code that stores a wrong value into the counter, or tools/dashboards reading the counter concurrently with it being closed and returning -1.

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

• invalid state counter code:
• invalid toggle value
• - code must equal ordinal value: code=
• - joinPosition= than logPosition=
• counter is closed

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ElectionState.java:151

     *
     * @return code stored in a {@link io.aeron.Counter} to represent the election state.
     */
    public int code()
    {
        return code;
    }

    /**
     * Get the enum value for a given code stored in a counter.
     *
     * @param code representing election state.
     * @return the enum value for a given code stored in a counter.
     */
    public static ElectionState get(final long code)
    {
        if (code < 0 || code > (STATES.length - 1))
        {
            throw new ClusterException("invalid election state counter code: " + code);
        }

        return STATES[(int)code];
    }

    /**
     * Get the {@link ElectionState} value based on the value stored in an {@link AtomicCounter}.
     *
     * @param counter to read the value for matching against {@link #code()}.
     * @return the {@link ElectionState} value based on the value stored in an {@link AtomicCounter}.
     */
    public static ElectionState get(final AtomicCounter counter)
    {
        if (counter.isClosed())
        {
            return CLOSED;
        }

View on GitHub (pinned to 6d60124e15)