{"record":{"id":"3b7811035e1f3246","repo":"aeron-io/aeron","slug":"matching-tag-has-mismatched-endpoint-or-control","errorCode":null,"errorMessage":"matching tag= has mismatched endpoint or control:  <> ","messagePattern":"matching tag= has mismatched endpoint or control:  <> ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java","lineNumber":799,"sourceCode":"    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;\n    }\n\n    private boolean hasMatchingControlMode(final UdpChannel udpChannel)\n    {\n        return controlMode() == ControlMode.NONE || controlMode() == udpChannel.controlMode();\n    }","sourceCodeStart":781,"sourceCodeEnd":817,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java#L781-L817","documentation":"Thrown by UdpChannel.isEquivalentTo when two channel URIs with the same matching tag resolve to different endpoint or control addresses. Channels sharing a tag must refer to the same transport addresses.","triggerScenarios":"Two URIs with identical tags= value but different endpoint= values (e.g. endpoint=host1:40456 vs endpoint=host2:40456), or differing control addresses.","commonSituations":"Copy-paste errors in URI templates, services reusing a tag across environments, dynamic channel strings built with wrong host variables.","solutions":["Ensure endpoint/control addresses match exactly for all URIs sharing a tag","Use different tags for different destinations","Rebuild the URI with the correct host/port for the shared tag"],"exampleFix":"// before\n\"aeron:udp?tags=1001|endpoint=h1:40456\" and \"aeron:udp?tags=1001|endpoint=h2:40456\"\n// after\n\"aeron:udp?tags=1001|endpoint=h1:40456\" and \"aeron:udp?tags=1001|endpoint=h1:40456\"","handlingStrategy":"validation","validationCode":"String prev = tagToAddr.putIfAbsent(tag, endpoint + \"|\" + control);\nif (prev != null && !prev.equals(endpoint + \"|\" + control)) throw new IllegalArgumentException(\"tag \" + tag + \" reused with different addresses\");","typeGuard":"static boolean addressesMatch(String uriA, String uriB) { return Objects.equals(extractParam(uriA, \"endpoint\"), extractParam(uriB, \"endpoint\")) && Objects.equals(extractParam(uriA, \"control\"), extractParam(uriB, \"control\")); }","tryCatchPattern":"try { checkEquivalent(channelA, channelB); } catch (IllegalArgumentException e) { throw new ConfigException(\"shared tag must keep same endpoint/control: \" + e.getMessage()); }","preventionTips":["Keep a registry mapping tag -> (endpoint, control, control-mode)","Never hardcode the same tags value in independent config files","Build URIs programmatically from a single source of truth"],"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"}