aeron-io/aeron · error · IllegalArgumentException

multicast data address must be odd

Error message

multicast data address must be odd

What it means

For multicast (MDC) data channels, Aeron requires the multicast data address's last byte to be odd, per IP multicast addressing conventions (even last octet is not a valid host-group assignment in Aeron's scheme). validateDataAddress throws IllegalArgumentException when the final byte of the endpoint address is even.

Solutions

1. Change the multicast data address so its last octet is odd (e.g. 239.255.0.2 -> 239.255.0.3).
2. Generate/allocate multicast addresses programmatically with an odd final byte.
3. Document your multicast allocation plan so even addresses are never assigned to data channels.

Example fix

// before
"aeron:udp?endpoint=239.255.0.2:40456"
// after
"aeron:udp?endpoint=239.255.0.3:40456"

byte last = (byte) InetAddresses.coerceToInteger(InetAddress.getByName(mcastAddr));
// check last octet before building URI
if ((InetAddress.getByName(mcastAddr).getAddress()[3] & 0xFF) % 2 == 0) {
    throw new IllegalArgumentException("multicast data address must be odd");
}

When it happens

Trigger: Configuring a UdpChannel with a multicast endpoint address whose last octet is even, e.g. endpoint=239.255.0.2, then parsing the channel via UdpChannel.parse.

Common situations: Administrators copying even-numbered multicast group addresses from documentation or other middleware; generating addresses programmatically by incrementing and landing on an even octet.

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

• unresolved - control=, name-resolver=
• interface is null or empty
• invalid fileIoMaxLength=
• segment file length not a power of 2
• segment file length not in valid range

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

Appendix: source

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

            address = SocketAddressParser.parse(
                controlValue, MDC_CONTROL_PARAM_NAME, false, nameResolver);

            if (address.isUnresolved())
            {
                throw new UnknownHostException(
                    "unresolved - " + MDC_CONTROL_PARAM_NAME + "=" + controlValue +
                    ", name-resolver=" + nameResolver.getClass().getName());
            }
        }

        return address;
    }

    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
    {

View on GitHub (pinned to 6d60124e15)