{"record":{"id":"977fb49557613316","repo":"aeron-io/aeron","slug":"invalid-role-counter-code-code","errorCode":null,"errorMessage":"Invalid role counter code: <code>","messagePattern":"Invalid role counter code: <code>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/Cluster.java","lineNumber":102,"sourceCode":"         *\n         * @return the code which matches the role in the cluster.\n         */\n        public final int code()\n        {\n            return code;\n        }\n\n        /**\n         * Get the role from a code read from a counter.\n         *\n         * @param code for the {@link Role}.\n         * @return the {@link Role} of the cluster node.\n         */\n        public static Role get(final long code)\n        {\n            if (code < 0 || code > (ROLES.length - 1))\n            {\n                throw new IllegalStateException(\"Invalid role counter code: \" + code);\n            }\n\n            return ROLES[(int)code];\n        }\n\n        /**\n         * Get the role by reading the code from a counter.\n         *\n         * @param counter containing the value of the role.\n         * @return the role for the cluster member.\n         */\n        public static Role get(final AtomicCounter counter)\n        {\n            if (counter.isClosed())\n            {\n                return FOLLOWER;\n            }\n","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/Cluster.java#L84-L120","documentation":"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.","triggerScenarios":"Reading the cluster's role counter (Counter) when it was never initialized, corrupted, or written by an incompatible Aeron version with more/fewer roles.","commonSituations":"Stale or reused counters from a previous cluster run with different counters.dat; agent/monitoring code reading a counter before the container sets it.","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"],"exampleFix":"// before\nCluster.Role role = Cluster.Role.get(roleCounter.get());\n// after\nlong code = roleCounter.get();\nCluster.Role role = (code >= 0 && code <= 2)\n    ? Cluster.Role.get(code)\n    : Cluster.Role.FOLLOWER; // or handle uninitialized state","handlingStrategy":"try-catch","validationCode":"long code = roleCounter.get();\nboolean valid = code >= 0 && code <= Cluster.Role.values().length - 1;","typeGuard":null,"tryCatchPattern":"try {\n    Cluster.Role role = Cluster.Role.get(roleCounter.get());\n} catch (IllegalStateException ex) {\n    // counter uninitialized or corrupt: treat node as not started\n}","preventionTips":["Never reuse counters from previous cluster runs","Start monitoring only after the container initializes counters","Validate counter values before mapping to Role"],"tags":["aeron","cluster","counter","enum"],"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"}