{"record":{"id":"ab5a9bc1dc06c4ae","repo":"aeron-io/aeron","slug":"invalid-channel","errorCode":"INVALID_CHANNEL","errorMessage":"channel does not allow manual control","messagePattern":"channel does not allow manual control","errorType":"error_code","errorClass":"ControlProtocolException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/ReceiveChannelEndpoint.java","lineNumber":505,"sourceCode":"     * Has the channel got control of destinations for MDS.\n     *\n     * @return true if the channel got control of destinations for MDS.\n     */\n    public boolean hasDestinationControl()\n    {\n        return null != multiRcvDestination;\n    }\n\n    /**\n     * Validate that the channel allows destination control.\n     * <p>\n     * If not then a {@link ControlProtocolException} will be thrown.\n     */\n    public void validateAllowsDestinationControl()\n    {\n        if (null == multiRcvDestination)\n        {\n            throw new ControlProtocolException(ErrorCode.INVALID_CHANNEL, \"channel does not allow manual control\");\n        }\n    }\n\n    /**\n     * Is the primary transport multicast?\n     *\n     * @return true if the primary transport is multicast.\n     */\n    public boolean isMulticast()\n    {\n        return isMulticast(0);\n    }\n\n    /**\n     * Is a given transport index multicast?\n     *\n     * @param transportIndex to check for multicast.\n     * @return true if the transport index is multicast.","sourceCodeStart":487,"sourceCodeEnd":523,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/ReceiveChannelEndpoint.java#L487-L523","documentation":"Aeron throws ControlProtocolException(ErrorCode.INVALID_CHANNEL) when a manual (MDC) control operation such as adding/removing destinations is requested on a receive channel endpoint that is not configured as a multi-destination (no MultiRcvDestination). Only channels created with control-mode=manual support dynamic destination control.","triggerScenarios":"Driver command ADD_RCV_DESTINATION/REMOVE_RCV_DESTINATION arrives for a subscription whose ReceiveChannelEndpoint was created from a plain (non-manual) URI, so validateAllowsDestinationControl finds multiRcvDestination == null.","commonSituations":"Calling Subscription.addDestination (or driver client addRcvDestination) on a subscription created from a normal aeron:udp?endpoint=... URI instead of one with control-mode=manual; mixing manual and non-manual channels in MDC setups.","solutions":["Create the subscription channel with control-mode=manual in the URI, e.g. aeron:udp?control-mode=manual","Restructure code so destination add/remove calls are only made on subscriptions created for manual multi-destination control","Catch ControlProtocolException and check getErrorCode() == ErrorCode.INVALID_CHANNEL to surface the misconfigured channel"],"exampleFix":"// before\nSubscription sub = aeron.addSubscription(\"aeron:udp?endpoint=127.0.0.1:40456\", 1001);\nsub.addDestination(\"aeron:udp?endpoint=127.0.0.1:40457\"); // throws\n// after\nSubscription sub = aeron.addSubscription(\"aeron:udp?control-mode=manual\", 1001);\nsub.addDestination(\"aeron:udp?endpoint=127.0.0.1:40457\");","handlingStrategy":"try-catch","validationCode":"boolean manual = uri.contains(\"control-mode=manual\");\nif (!manual) throw new IllegalStateException(\"receive channel must use control-mode=manual for addDestination\");","typeGuard":null,"tryCatchPattern":"try {\n    subscription.addDestination(dstUri);\n} catch (ControlProtocolException e) {\n    if (e.errorCode() == ErrorCode.INVALID_CHANNEL) { /* recreate subscription with control-mode=manual */ }\n}","preventionTips":["Always create MDC receive channels with control-mode=manual","Centralize channel URI construction in one helper that enforces the mode","Only call addDestination/removeDestination on subscriptions you created as manual"],"tags":["aeron","mdc","configuration","channel"],"backgroundTag":"invalid-config-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"}