aeron-io/aeron · error · IllegalArgumentException

UdpChannel only supports UDP media:

Error message

UdpChannel only supports UDP media: 

What it means

A ChannelUri whose media/type is not 'udp' was passed to UdpChannel, which only handles UDP transport. validateMedia checks uri.isUdp() and throws IllegalArgumentException otherwise, preventing an IPC or other-transport URI from being treated as a network channel.

Solutions

1. Ensure the channel URI starts with 'aeron:udp' for network transport.
2. Use the IPC path (Aeron's ipc channel handling) instead of UdpChannel for 'aeron:ipc' URIs.
3. Add a check that dispatches on uri.media()/scheme before calling UdpChannel.parse.

Example fix

// before
String uri = "aeron:ipc";
UdpChannel.parse(uri); // throws
// after
String uri = "aeron:udp?endpoint=localhost:40456";
if (ChannelUri.parse(uri).isUdp()) {
    UdpChannel.parse(uri);
}

ChannelUri uri = ChannelUri.parse(channelStr);
if (!"udp".equals(uri.media())) { /* route to IPC or other transport handler */ }

boolean isUdpChannel(String s) {
    return s != null && s.startsWith("aeron:udp");
}

try {
    UdpChannel.parse(uriStr);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("only supports UDP")) { /* dispatch non-UDP transport */ }
}

When it happens

Trigger: Passing a URI like 'aeron:ipc' or an unknown scheme (e.g. 'aeron:tcp' if unsupported) to UdpChannel.parse, or publishing/subscribing with a channel URI missing or mistyping the media component.

Common situations: Configuration mixing IPC and UDP channels, a typo in the URI scheme, or generic channel-handling code that assumes all URIs are UDP and forwards them to UdpChannel.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• AeronCluster.Context.clientName length must be <=…
• AeronCluster.Context ingressEndpoints must be null when…
• applicationSpecificFeedback length must be equal to
• clientLivenessTimeoutNs=

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

Appendix: source

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

    private static void validateDataAddress(final byte[] addressAsBytes)
    {
        if (BitUtil.isEven(addressAsBytes[addressAsBytes.length - 1]))
        {
            throw new IllegalArgumentException("multicast data address must be odd");
        }
    }

    private static void validateConfiguration(final ChannelUri uri)
    {
        validateMedia(uri);
    }

    private static void validateMedia(final ChannelUri uri)
    {
        if (!uri.isUdp())
        {
            throw new IllegalArgumentException("UdpChannel only supports UDP media: " + uri);
        }
    }

    static final class Context
    {
        ControlMode controlMode = ControlMode.NONE;
        boolean hasExplicitEndpoint = false;
        boolean hasExplicitControl = false;
        boolean isMulticast = false;
        boolean hasMulticastTtl = false;
        boolean hasTagId = false;
        boolean hasNoDistinguishingCharacteristic = false;
        int socketRcvbufLength = 0;
        int socketSndbufLength = 0;
        int receiverWindowLength = 0;
        int multicastTtl;
        long tagId;
        InetSocketAddress remoteData;

View on GitHub (pinned to 6d60124e15)