{"record":{"id":"aeca25477011d707","repo":"aeron-io/aeron","slug":"invalid-state-counter-code-code","errorCode":null,"errorMessage":"invalid state counter code: ${code}","messagePattern":"invalid state counter code: (.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java","lineNumber":232,"sourceCode":"            {\n                return CLOSED;\n            }\n\n            return get(counter.get());\n        }\n\n        /**\n         * Get the {@link State} corresponding to a particular code.\n         *\n         * @param code representing a {@link State}.\n         * @return the {@link State} corresponding to the provided code.\n         * @throws ClusterException if the code does not correspond to a valid State.\n         */\n        public static State get(final long code)\n        {\n            if (code < 0 || code > (STATES.length - 1))\n            {\n                throw new ClusterException(\"invalid state counter code: \" + code);\n            }\n\n            return STATES[(int)code];\n        }\n\n        /**\n         * Get the current state of the {@link ConsensusModule}.\n         *\n         * @param counters  to search within.\n         * @param clusterId to which the allocated counter belongs.\n         * @return the state of the ConsensusModule or null if not found.\n         */\n        public static State find(final CountersReader counters, final int clusterId)\n        {\n            final int counterId = ClusterCounters.find(counters, CONSENSUS_MODULE_STATE_TYPE_ID, clusterId);\n            if (Aeron.NULL_VALUE != counterId)\n            {\n                return State.get(counters.getCounterValue(counterId));","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java#L214-L250","documentation":"ConsensusModule.State.get maps a counter code to a State enum value and rejects codes outside the valid range [0, STATES.length-1] with ClusterException \"invalid state counter code\". The code comes from the consensus module's status counter, so an out-of-range code means the counter was corrupted or written by an incompatible component.","triggerScenarios":"Reading the consensus module's status counter (CounterListener / get(code)) where the counter value is negative or greater than the number of defined States (e.g. reading a counter Id instead of its value, or a counter written by a different Aeron version).","commonSituations":"Application code reading the wrong counter (using counterId as the code); stale/corrupted counters left in a reused Aeron directory; mixing Aeron versions between the media driver and cluster where state encodings differ; agents aggregating counters incorrectly.","solutions":["Verify you read the counter's value, not its registration/counter id, before mapping to State.","Ensure the Aeron driver and cluster versions match across all components.","Check that no other process is writing to the consensus module status counter.","If counters come from a corrupted mark/counters file, stop the node and clear the Aeron directory (aeron.directory.delete.on.start=true) before restart."],"exampleFix":"// before\nlong code = counter.counterId(); // wrong: id, not value\nState state = ConsensusModule.State.get(code);\n// after\nlong code = counter.get(); // actual counter value\nif (code >= 0 && code < ConsensusModule.State.values().length)\n{\n    State state = ConsensusModule.State.get(code);\n}","handlingStrategy":"validation","validationCode":"long code = counter.get();\nif (code < 0 || code >= ConsensusModule.State.values().length)\n{\n    throw new IllegalStateException(\"invalid state counter code: \" + code);\n}","typeGuard":"boolean isValidStateCode(long code)\n{\n    return code >= 0 && code < ConsensusModule.State.values().length;\n}","tryCatchPattern":"try\n{\n    State state = ConsensusModule.State.get(code);\n}\ncatch (ClusterException ex)\n{\n    if (!ex.getMessage().startsWith(\"invalid state counter code\")) throw ex;\n    // re-read the counter value; check driver/agent version alignment\n}","preventionTips":["Read the counter's value (counter.get()), never its id.","Use Aeron's CounterListener/inspectors rather than hand-rolled counter parsing.","Keep driver, client and cluster versions aligned; clear stale Aeron dirs when upgrading."],"tags":["aeron","cluster","counter","invalid-value"],"backgroundTag":"invalid-enum-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}