{"record":{"id":"359e8c3104158b7f","repo":"aeron-io/aeron","slug":"invalid-toggle-value-togglevalue","errorCode":null,"errorMessage":"invalid toggle value: ${toggleValue}","messagePattern":"invalid toggle value: (.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterControl.java","lineNumber":175,"sourceCode":"\n        /**\n         * Get the {@link ToggleState} for a given control toggle.\n         *\n         * @param controlToggle to get the current state for.\n         * @return the state for the current control toggle.\n         * @throws ClusterException if the counter is not one of the valid values.\n         */\n        public static ToggleState get(final AtomicCounter controlToggle)\n        {\n            if (controlToggle.isClosed())\n            {\n                throw new ClusterException(\"counter is closed\");\n            }\n\n            final long toggleValue = controlToggle.get();\n            if (toggleValue < 0 || toggleValue > (STATES.length - 1))\n            {\n                throw new ClusterException(\"invalid toggle value: \" + toggleValue);\n            }\n\n            return STATES[(int)toggleValue];\n        }\n    }\n\n    private ClusterControl()\n    {\n    }\n\n    /**\n     * Counter type id for the control toggle.\n     */\n    public static final int CONTROL_TOGGLE_TYPE_ID = AeronCounters.CLUSTER_CONTROL_TOGGLE_TYPE_ID;\n\n    /**\n     * Map a {@link CountersReader} over the provided {@link File} for the CnC file.\n     *","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterControl.java#L157-L193","documentation":"ClusterControl.ToggleState.get validates that the counter's raw value indexes into the known STATES array; values below 0 or beyond the last state are rejected with this message. It indicates memory corruption, a version mismatch, or reading an uninitialised counter.","triggerScenarios":"The AtomicCounter's value read via controlToggle.get() is < 0 or > STATES.length-1 (outside the 0..N toggle state range).","commonSituations":"Two nodes on different Aeron versions sharing a counter, an uninitialised/freshly allocated counter being read, or external writes to the counter buffer.","solutions":["Verify all components use the same Aeron version","Ensure the control toggle counter is initialised to a valid ToggleState ordinal before use","Check nothing else writes into the counters buffer (buffer overrun/corruption)","Log and clamp the raw value to diagnose which invalid value is produced"],"exampleFix":"// before\nlong v = toggle.get(); // may be -1 before init\n// after\nif (toggle.isClosed() || toggle.get() < 0 || toggle.get() >= ClusterControl.ToggleState.STATES.length) {\n    throw new IllegalStateException(\"toggle not initialised: \" + toggle.get());\n}","handlingStrategy":"validation","validationCode":"long v = controlToggle.get();\nif (v < 0 || v >= ClusterControl.ToggleState.STATES.length) {\n    throw new IllegalStateException(\"toggle value out of range: \" + v);\n}","typeGuard":null,"tryCatchPattern":"try {\n    ToggleState s = ClusterControl.ToggleState.get(controlToggle);\n} catch (ClusterException e) {\n    // dump raw value and component versions for corruption diagnosis\n}","preventionTips":["Use identical Aeron versions across all members","Initialise counters to a valid state before publication","Guard the counters buffer from external writers"],"tags":["aeron","state","corruption","value-out-of-range"],"backgroundTag":"value-out-of-range","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"}