{"record":{"id":"916e6d9394fc31c9","repo":"aeron-io/aeron","slug":"invalid-control-mode-controlmode","errorCode":null,"errorMessage":"invalid control mode: ${controlMode}","messagePattern":"invalid control mode: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":460,"sourceCode":"     * Set the control mode for multi-destination-cast. Set to \"manual\" for allowing control from the publication API.\n     *\n     * @param controlMode for taking control of MDC.\n     * @return this for a fluent API.\n     * @see Publication#addDestination(String)\n     * @see Publication#removeDestination(String)\n     * @see CommonContext#MDC_CONTROL_MODE_PARAM_NAME\n     * @see CommonContext#MDC_CONTROL_MODE_MANUAL\n     * @see CommonContext#MDC_CONTROL_MODE_DYNAMIC\n     * @see CommonContext#CONTROL_MODE_RESPONSE\n     */\n    public ChannelUriStringBuilder controlMode(final String controlMode)\n    {\n        if (null != controlMode &&\n            !controlMode.equals(MDC_CONTROL_MODE_MANUAL) &&\n            !controlMode.equals(MDC_CONTROL_MODE_DYNAMIC) &&\n            !controlMode.equals(CONTROL_MODE_RESPONSE))\n        {\n            throw new IllegalArgumentException(\"invalid control mode: \" + controlMode);\n        }\n\n        this.controlMode = controlMode;\n        return this;\n    }\n\n    /**\n     * Set the control mode to be what is in the {@link ChannelUri} which may be null.\n     *\n     * @param channelUri to read the value from.\n     * @return this for a fluent API.\n     * @see CommonContext#MDC_CONTROL_MODE_PARAM_NAME\n     */\n    public ChannelUriStringBuilder controlMode(final ChannelUri channelUri)\n    {\n        return controlMode(channelUri.get(MDC_CONTROL_MODE_PARAM_NAME));\n    }\n","sourceCodeStart":442,"sourceCodeEnd":478,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L442-L478","documentation":"Thrown by ChannelUriStringBuilder.controlMode(String) when the control mode is not one of the allowed values: manual, dynamic, or response. The control mode tells the driver how multicast control messages are managed, so unknown values are rejected at build time.","triggerScenarios":"builder.controlMode(\"static\"), builder.controlMode(\"manual-dynamic\"), or a config string that isn't exactly MDC_CONTROL_MODE_MANUAL / MDC_CONTROL_MODE_DYNAMIC / CONTROL_MODE_RESPONSE.","commonSituations":"Guessing mode names (\"auto\", \"static\"); case mismatch (\"MANUAL\"); upgrading from older Aeron versions where only manual/dynamic existed and using a stale constant.","solutions":["Use ChannelUriStringBuilder.MDC_CONTROL_MODE_MANUAL (\"manual\").","Use ChannelUriStringBuilder.MDC_CONTROL_MODE_DYNAMIC (\"dynamic\").","Use CONTROL_MODE_RESPONSE (\"response\") if response channels are intended; otherwise omit controlMode."],"exampleFix":"// before\nbuilder.controlMode(\"static\");\n// after\nbuilder.controlMode(ChannelUriStringBuilder.MDC_CONTROL_MODE_MANUAL);","handlingStrategy":"validation","validationCode":"Set<String> OK = Set.of(ChannelUriStringBuilder.MDC_CONTROL_MODE_MANUAL, ChannelUriStringBuilder.MDC_CONTROL_MODE_DYNAMIC, ChannelUriStringBuilder.CONTROL_MODE_RESPONSE);\nif (mode != null && !OK.contains(mode)) { throw new IllegalArgumentException(\"invalid control mode: \" + mode); }","typeGuard":"boolean isValidControlMode(String m) { return m == null || ChannelUriStringBuilder.MDC_CONTROL_MODE_MANUAL.equals(m) || ChannelUriStringBuilder.MDC_CONTROL_MODE_DYNAMIC.equals(m) || ChannelUriStringBuilder.CONTROL_MODE_RESPONSE.equals(m); }","tryCatchPattern":"try { builder.controlMode(m); } catch (IllegalArgumentException e) { builder.controlMode(ChannelUriStringBuilder.MDC_CONTROL_MODE_MANUAL); }","preventionTips":["Use the builder's public constants, not literals","Validate an enum in your config layer before mapping to the string","Lowercase/trim user input before setting"],"tags":["aeron","channel-uri","validation","configuration"],"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"}