aeron-io/aeron · error · IllegalArgumentException

invalid media

Error message

invalid media: ${media}

What it means

Thrown by ChannelUriStringBuilder.media(String) when the media is not one of the supported transports: "udp", "ipc" (and the network's alias "network" if accepted upstream). The builder only emits URIs the driver can resolve to a transport.

Solutions

1. Use CommonContext.UDP_MEDIA ("udp") for network transport.
2. Use CommonContext.IPC_MEDIA ("ipc") for shared-memory transport.
3. Trim/lowercase and validate config-provided media strings before calling media().

Example fix

// before
builder.media("tcp");
// after
builder.media(CommonContext.UDP_MEDIA);

Set<String> OK = Set.of(CommonContext.UDP_MEDIA, CommonContext.IPC_MEDIA);
if (media != null && !OK.contains(media)) { throw new IllegalArgumentException("invalid media: " + media); }

boolean isValidMedia(String media) { return media == null || CommonContext.UDP_MEDIA.equals(media) || CommonContext.IPC_MEDIA.equals(media); }

try { builder.media(m); } catch (IllegalArgumentException e) { builder.media(CommonContext.UDP_MEDIA); }

When it happens

Trigger: builder.media("tcp"), builder.media("UDP") with unexpected case handling, or passing a free-form string from configuration.

Common situations: Using transports Aeron doesn't support here (e.g. "tcp"); case mismatch; copy-pasting media values from other messaging systems (e.g. "rdma").

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• URI length ( ) exceeds max supported length ( )…
• difference greater than 2^31 - 1: termId=
• termOffset= > termLength=
• invalid prefix
• invalid control mode

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java:304

        return prefix;
    }

    /**
     * Set the media for this channel. Valid values are "udp" and "ipc".
     *
     * @param media for this channel.
     * @return this for a fluent API.
     */
    public ChannelUriStringBuilder media(final String media)
    {
        switch (media)
        {
            case CommonContext.UDP_MEDIA:
            case CommonContext.IPC_MEDIA:
                break;

            default:
                throw new IllegalArgumentException("invalid media: " + media);
        }

        this.media = media;
        return this;
    }

    /**
     * Set the endpoint value to be what is in the {@link ChannelUri}.
     *
     * @param channelUri to read the value from.
     * @return this for a fluent API.
     */
    public ChannelUriStringBuilder media(final ChannelUri channelUri)
    {
        return media(channelUri.media());
    }

    /**

View on GitHub (pinned to 6d60124e15)