What causes "unknown media: ${media}" in aeron-io/aeron?

Change the URI media to "udp" or "ipc" (lowercase, exactly)

aeron-io/aeron · error · IllegalArgumentException

unknown media

Error message

unknown media: ${media}

What it means

ChannelUri.validateMedia() (used by media() and parse()) accepts only "ipc" or "udp" as the URI media component; anything else throws IllegalArgumentException. The media determines the transport type of the Aeron channel.

Solutions

Change the URI media to "udp" or "ipc" (lowercase, exactly)
If you need a different transport, check the Aeron version/docs for supported media; this build supports only udp and ipc
Normalize/case-fold media values from config before constructing the URI

Example fix

// before
Aeron.connect().addPublication("aeron:tcp?endpoint=localhost:40456", streamId);
// after
Aeron.connect().addPublication("aeron:udp?endpoint=localhost:40456", streamId);

Defensive patterns

Strategy: validation

Validate before calling

static void requireSupportedMedia(String media) {
    if (!"udp".equals(media) && !"ipc".equals(media)) {
        throw new IllegalArgumentException("unsupported media '" + media + "', use 'udp' or 'ipc'");
    }
}

Type guard

static boolean isSupportedMedia(String media) {
    return "udp".equals(media) || "ipc".equals(media);
}

Try / catch

try {
    ChannelUri.parse(channelUri);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("unknown media")) {
        throw new IllegalArgumentException("Unsupported channel media in: " + channelUri, e);
    }
    throw e;
}

Prevention

Use only lowercase "udp" or "ipc" in channel URIs — matching is case-sensitive
Validate media from config files/environment against a whitelist before constructing URIs
Check Aeron docs for your version before assuming other transports (tcp, etc.) are supported

When it happens

Trigger: Calling ChannelUri.parse() on a URI like "aeron:tcp?endpoint=..." or "aeron:foo?...", or ChannelUri.media("tcp") — any media string other than "ipc" or "udp".

Common situations: Assuming other network protocols (tcp, websocket) are supported; typos like "UDP" (case matters) or "ip c"; migrating configs from other messaging systems.

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

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ChannelUri.java:698

    /**
     * Determines if the supplied channel has specified <code>control-mode=response</code>.
     *
     * @param channelUri to check if the control mode is response
     * @return true if the supplied channel has specified <code>control-mode=response</code>.
     */
    public static boolean isControlModeResponse(final String channelUri)
    {
        return parse(channelUri).hasControlModeResponse();
    }

    private static void validateMedia(final String media)
    {
        if (IPC_MEDIA.equals(media) || UDP_MEDIA.equals(media))
        {
            return;
        }

        throw new IllegalArgumentException("unknown media: " + media);
    }

    private static boolean startsWith(final CharSequence input, final int position, final String prefix)
    {
        if ((input.length() - position) < prefix.length())
        {
            return false;
        }

        for (int i = 0; i < prefix.length(); i++)
        {
            if (input.charAt(position + i) != prefix.charAt(i))
            {
                return false;
            }
        }

        return true;

View on GitHub (pinned to 6d60124e15)