aeron-io/aeron · error · IllegalArgumentException

matching tag= has mismatched endpoint or control: <>

Error message

matching tag= has mismatched endpoint or control:  <> 

What it means

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.

Solutions

1. Ensure endpoint/control addresses match exactly for all URIs sharing a tag
2. Use different tags for different destinations
3. Rebuild the URI with the correct host/port for the shared tag

Example fix

// before
"aeron:udp?tags=1001|endpoint=h1:40456" and "aeron:udp?tags=1001|endpoint=h2:40456"
// after
"aeron:udp?tags=1001|endpoint=h1:40456" and "aeron:udp?tags=1001|endpoint=h1:40456"

String prev = tagToAddr.putIfAbsent(tag, endpoint + "|" + control);
if (prev != null && !prev.equals(endpoint + "|" + control)) throw new IllegalArgumentException("tag " + tag + " reused with different addresses");

static boolean addressesMatch(String uriA, String uriB) { return Objects.equals(extractParam(uriA, "endpoint"), extractParam(uriB, "endpoint")) && Objects.equals(extractParam(uriA, "control"), extractParam(uriB, "control")); }

try { checkEquivalent(channelA, channelB); } catch (IllegalArgumentException e) { throw new ConfigException("shared tag must keep same endpoint/control: " + e.getMessage()); }

When it happens

Trigger: Two URIs with identical tags= value but different endpoint= values (e.g. endpoint=host1:40456 vs endpoint=host2:40456), or differing control addresses.

Common situations: Copy-paste errors in URI templates, services reusing a tag across environments, dynamic channel strings built with wrong host variables.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• entityTag already in use: existingChannel= channel=
• matching tag= has mismatched control-mode: <>
• Aeron URIs must start with 'aeron:', found
• channelReceiveTimestampOffset must be a number or the value
• channelSendTimestampOffset must be a number or the value

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/3b7811035e1f3246. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java:799

    public boolean matchesTag(
        final UdpChannel udpChannel,
        final InetSocketAddress localAddress,
        final InetSocketAddress remoteAddress)
    {
        if (!hasTag || !udpChannel.hasTag() || tag != udpChannel.tag())
        {
            return false;
        }

        if (!hasMatchingControlMode(udpChannel))
        {
            throw new IllegalArgumentException(
                "matching tag=" + tag + " has mismatched control-mode: " + uriStr + " <> " + udpChannel.uriStr);
        }

        if (!hasMatchingAddress(udpChannel, localAddress, remoteAddress))
        {
            throw new IllegalArgumentException(
                "matching tag=" + tag + " has mismatched endpoint or control: " + uriStr + " <> " + udpChannel.uriStr);
        }

        return true;
    }

    private boolean isWildcard()
    {
        return remoteData.getAddress().isAnyLocalAddress() &&
            remoteData.getPort() == 0 &&
            localData.getAddress().isAnyLocalAddress() &&
            localData.getPort() == 0;
    }

    private boolean hasMatchingControlMode(final UdpChannel udpChannel)
    {
        return controlMode() == ControlMode.NONE || controlMode() == udpChannel.controlMode();
    }

View on GitHub (pinned to 6d60124e15)