{"record":{"id":"974b3aa85dc66a11","repo":"aeron-io/aeron","slug":"code-must-equal-ordinal-value-code","errorCode":null,"errorMessage":" - code must equal ordinal value: code=","messagePattern":" - code must equal ordinal value: code=","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackup.java","lineNumber":152,"sourceCode":"        /**\n         * On error or progress stall the backup is reset and started over again.\n         */\n        RESET_BACKUP(6),\n\n        /**\n         * The backup is complete and closed.\n         */\n        CLOSED(7);\n\n        static final State[] STATES = values();\n\n        private final int code;\n\n        State(final int code)\n        {\n            if (code != ordinal())\n            {\n                throw new IllegalArgumentException(name() + \" - code must equal ordinal value: code=\" + code);\n            }\n\n            this.code = code;\n        }\n\n        /**\n         * Code which represents the {@link State} as an int.\n         *\n         * @return code which represents the {@link State} as an int.\n         */\n        public int code()\n        {\n            return code;\n        }\n\n        /**\n         * Get the {@link State} encoded in an {@link AtomicCounter}.\n         *","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackup.java#L134-L170","documentation":"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.","triggerScenarios":"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.","commonSituations":"Inserting a new state in the middle of the enum during an Aeron source modification or patch, or rebasing custom changes to ClusterBackup.java.","solutions":["Renumber the new State constant's code argument so it equals its ordinal position.","Append new states at the end of the enum with the next sequential code instead of inserting mid-list.","If a counter value changed meaning, keep ordinal order and map old codes explicitly rather than reordering."],"exampleFix":"// before\nINIT(0), BACKUP_COMPLETE(1), FAILED(3) // 3 != ordinal 2\n// after\nINIT(0), BACKUP_COMPLETE(1), FAILED(2)","handlingStrategy":"validation","validationCode":"for (int i = 0; i < State.values().length; i++) { assert State.values()[i].code() == i; }","typeGuard":null,"tryCatchPattern":"Not catchable by users: it fails at class-init. Fix the enum declaration in source.","preventionTips":["Always append new enum states with sequential codes","Add a unit test asserting code == ordinal for all states","Never reorder or delete existing states tied to persisted counters"],"tags":["enum","invariant","developer-error","aeron-cluster"],"backgroundTag":"internal-invariant-violation","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}