{"record":{"id":"07b804e3a48e31f5","repo":"aeron-io/aeron","slug":"matching-tag-has-mismatched-control-mode","errorCode":null,"errorMessage":"matching tag= has mismatched control-mode:  <> ","messagePattern":"matching tag= has mismatched control-mode:  <> ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java","lineNumber":793,"sourceCode":"     *\n     * @param udpChannel to match against.\n     * @param localAddress local address override to use for this channel.\n     * @param remoteAddress remote address override to use for this channel.\n     * @return true if there is a match otherwise false.\n     */\n    public boolean matchesTag(\n        final UdpChannel udpChannel,\n        final InetSocketAddress localAddress,\n        final InetSocketAddress remoteAddress)\n    {\n        if (!hasTag || !udpChannel.hasTag() || tag != udpChannel.tag())\n        {\n            return false;\n        }\n\n        if (!hasMatchingControlMode(udpChannel))\n        {\n            throw new IllegalArgumentException(\n                \"matching tag=\" + tag + \" has mismatched control-mode: \" + uriStr + \" <> \" + udpChannel.uriStr);\n        }\n\n        if (!hasMatchingAddress(udpChannel, localAddress, remoteAddress))\n        {\n            throw new IllegalArgumentException(\n                \"matching tag=\" + tag + \" has mismatched endpoint or control: \" + uriStr + \" <> \" + udpChannel.uriStr);\n        }\n\n        return true;\n    }\n\n    private boolean isWildcard()\n    {\n        return remoteData.getAddress().isAnyLocalAddress() &&\n            remoteData.getPort() == 0 &&\n            localData.getAddress().isAnyLocalAddress() &&\n            localData.getPort() == 0;","sourceCodeStart":775,"sourceCodeEnd":811,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java#L775-L811","documentation":"Thrown by UdpChannel.isEquivalentTo when two channel URIs sharing the same matching tag declare different control-mode values. Tagged channels that are expected to alias the same transport must agree on control-mode.","triggerScenarios":"Creating two subscriptions/publications whose URIs both set tags=... (matching tag) but one uses control-mode=manual and the other control-mode=common (or omits it).","commonSituations":"MDC setups where a dynamic control channel and a manual one reuse the same tag, config drift between services sharing a tag.","solutions":["Make control-mode identical for all URIs sharing the same tag","Use distinct tags for channels with different control modes","Remove the matching tag if the channels are intentionally different"],"exampleFix":"// before\n\"aeron:udp?tags=1001|control-mode=manual|control=...\" and \"aeron:udp?tags=1001|control-mode=common\"\n// after\n\"aeron:udp?tags=1001|control-mode=manual|control=...\" and \"aeron:udp?tags=1002|control-mode=common\"","handlingStrategy":"validation","validationCode":"Map<String,String> tagToMode = new HashMap<>();\nString mode = extractParam(uri, \"control-mode\");\nString prev = tagToMode.putIfAbsent(tag, mode);\nif (prev != null && !prev.equals(mode)) throw new IllegalArgumentException(\"tag \" + tag + \" reused with different control-mode\");","typeGuard":"static boolean controlModesMatch(String uriA, String uriB) { return Objects.equals(extractParam(uriA, \"control-mode\"), extractParam(uriB, \"control-mode\")); }","tryCatchPattern":"try { return channel.isEquivalentTo(other); } catch (IllegalArgumentException e) { log.warn(\"tagged channel mismatch: {}\", e.getMessage()); return false; }","preventionTips":["Generate all channel URIs sharing a tag from one template","Assign unique tags per logical channel","Include control-mode in tag-registry records"],"tags":["aeron","channel-uri","tags"],"backgroundTag":"conflicting-config-options","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}