aeron-io/aeron · error · IllegalArgumentException

encountered ' ' within media definition at index in

Error message

encountered '<c>' within media definition at index <i> in <uri>

What it means

During ChannelUri.parse, once inside the media definition section (between 'aeron:' and '?', e.g. 'udp'), the characters ':', '|', and '=' are not allowed. Their presence means a malformed URI — most often a scheme/transport separator typo — so parsing aborts with the offending character, its index, and the URI.

Solutions

  1. Use correct Aeron URI syntax: 'aeron:udp?endpoint=host:port' — ':' and '=' only appear after the '?' in parameters.
  2. Fix any string-building code that inserts '://' after the media (Aeron URIs do not use '://').
  3. Validate channel strings with a lint/regex check at config load to catch this before driver setup.
  4. Log the full URI on channel setup failures so malformed syntax is obvious.

Example fix

// before
String channel = "aeron:udp://localhost:40456";
// after
String channel = "aeron:udp?endpoint=localhost:40456";
Defensive patterns

Strategy: validation

Validate before calling

if (channel.startsWith("aeron:udp://") || channel.startsWith("aeron:ipc://")) {
    channel = channel.replaceFirst("://", "?"); // 'aeron:udp://x' is invalid; use 'aeron:udp?...'
}

Try / catch

try {
    ChannelUri uri = ChannelUri.parse(channel);
} catch (IllegalArgumentException e) {
    log.error("malformed Aeron URI: " + e.getMessage());
}

Prevention

When it happens

Trigger: Parsing a URI like 'aeron:udp:port=... or 'aeron:udp|...' — any of ':', '|', '=' appearing in the media/transport section, usually from writing 'aeron:udp://host' (the '//' and ':' belong after '?').

Common situations: Copy-pasting a URL-style URI ('aeron:udp://endpoint:port') instead of Aeron syntax ('aeron:udp?endpoint=host:port'); confusion between the legacy spy prefix and transport syntax; URI built by naive string concatenation.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

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

        State state = State.MEDIA;
        for (int i = position; i < length; i++)
        {
            final char c = uri.charAt(i);
            switch (state)
            {
                case MEDIA:
                    switch (c)
                    {
                        case '?':
                            media = builder.toString();
                            builder.setLength(0);
                            state = State.PARAMS_KEY;
                            break;

                        case ':':
                        case '|':
                        case '=':
                            throw new IllegalArgumentException(
                                "encountered '" + c + "' within media definition at index " + i + " in " + uri);

                        default:
                            builder.append(c);
                    }
                    break;

                case PARAMS_KEY:
                    if (c == '=')
                    {
                        if (builder.isEmpty())
                        {
                            throw new IllegalStateException("empty key not allowed at index " + i + " in " + uri);
                        }
                        key = builder.toString();
                        builder.setLength(0);
                        state = State.PARAMS_VALUE;
                    }

View on GitHub (pinned to 6d60124e15)