{"record":{"id":"e5722b3bf4df72a7","repo":"aeron-io/aeron","slug":"invalid-toggle-value-togglevalue-nodecontrol","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/NodeControl.java","lineNumber":144,"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    /**\n     * Counter type id for the control toggle.\n     */\n    public static final int CONTROL_TOGGLE_TYPE_ID = AeronCounters.NODE_CONTROL_TOGGLE_TYPE_ID;\n\n    private NodeControl()\n    {\n    }\n\n    /**\n     * Find the control toggle counter or return null if not found.\n     *","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/NodeControl.java#L126-L162","documentation":"NodeControl.ToggleState.get validates that the control-toggle counter holds a code in the range of valid ToggleState values (0..STATES.length-1). Values outside that range cannot map to a toggle state, so a ClusterException naming the value is thrown.","triggerScenarios":"The control-toggle AtomicCounter was written with an out-of-range value (e.g. -1 from a NULL/initial value, or an arbitrary integer set by external tooling via the counters manager), then read by ToggleState.get.","commonSituations":"External monitoring tools or admin code writing to the cluster control counter; reading before the toggle was initialized; version mismatch where newer software defines more states than an old counter file implies.","solutions":["Only write documented ToggleState codes to the control counter","Initialize/validate the counter value before first read","Treat negative values as 'not set' and skip processing","Make sure external tooling uses the same NodeControl.ToggleState codes as the cluster version"],"exampleFix":"// before\ncontrolToggle.set(99); // arbitrary code\ncontrolToggle.set(NodeControl.ToggleState.SUSPEND.code());\n// after\ncontrolToggle.set(NodeControl.ToggleState.SUSPEND.code());","handlingStrategy":"validation","validationCode":"long v = counter.get(); if (v < 0 || v >= NodeControl.ToggleState.values().length) return null;","typeGuard":"boolean isValidToggle(long v) { return v >= 0 && v < NodeControl.ToggleState.values().length; }","tryCatchPattern":"try { ts = NodeControl.ToggleState.get(controlToggle); } catch (ClusterException e) { ts = ToggleState.NEUTRAL; }","preventionTips":["Write only ToggleState.code() values into the control counter","Align external tooling with the cluster's enum codes","Initialize the counter before first read"],"tags":["aeron-cluster","counter","enum","control-toggle"],"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-16T04:17:20.429Z"}