aeron-io/aeron · error · IllegalArgumentException

- code must equal ordinal value: code=

Error message

 - code must equal ordinal value: code=

What it means

ClusterBackup.State is an enum whose internal counter code must equal the enum ordinal. The private constructor enforces this invariant at class initialization and throws IllegalArgumentException if a State constant is declared with a code that does not match its position. This guarantees the counter value read from the system can be used directly as a STATES array index.

Solutions

1. Renumber the new State constant's code argument so it equals its ordinal position.
2. Append new states at the end of the enum with the next sequential code instead of inserting mid-list.
3. If a counter value changed meaning, keep ordinal order and map old codes explicitly rather than reordering.

Example fix

// before
INIT(0), BACKUP_COMPLETE(1), FAILED(3) // 3 != ordinal 2
// after
INIT(0), BACKUP_COMPLETE(1), FAILED(2)

for (int i = 0; i < State.values().length; i++) { assert State.values()[i].code() == i; }

Not catchable by users: it fails at class-init. Fix the enum declaration in source.

When it happens

Trigger: Only at ClusterBackup.State class initialization — a developer adding/reordering enum constants (e.g. State("X", 5) in third position) so that code != ordinal(). Not reachable by normal library users.

Common situations: Inserting a new state in the middle of the enum during an Aeron source modification or patch, or rebasing custom changes to ClusterBackup.java.

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

• invalid state counter code:
• invalid election state counter code
• invalid toggle value
• id already in use
• <name()> - code must equal ordinal value: code=

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackup.java:152

        /**
         * On error or progress stall the backup is reset and started over again.
         */
        RESET_BACKUP(6),

        /**
         * The backup is complete and closed.
         */
        CLOSED(7);

        static final State[] STATES = values();

        private final int code;

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

            this.code = code;
        }

        /**
         * Code which represents the {@link State} as an int.
         *
         * @return code which represents the {@link State} as an int.
         */
        public int code()
        {
            return code;
        }

        /**
         * Get the {@link State} encoded in an {@link AtomicCounter}.
         *

View on GitHub (pinned to 6d60124e15)