aeron-io/aeron · error · IllegalArgumentException

Aeron URIs must start with 'aeron:', found

Error message

Aeron URIs must start with 'aeron:', found: <uri>

What it means

Every Aeron channel URI must begin with the 'aeron:' scheme prefix (optionally after the 'aeron-spy:' spy prefix). ChannelUri.parse throws IllegalArgumentException when the URI at the current position lacks this prefix, echoing the full offending string.

Solutions

1. Ensure the channel string starts with 'aeron:', e.g. 'aeron:udp?endpoint=localhost:40456'.
2. If you only have a transport string like 'udp?endpoint=...', prepend the scheme: "aeron:" + transport.
3. Validate/normalize channel configuration at startup and fail fast with a clear message.
4. Check for scheme-stripping in config handling (properties parsing, env vars, YAML quoting).

Example fix

// before
String channel = "udp?endpoint=224.0.1.1:40456";
// after
String channel = "aeron:udp?endpoint=224.0.1.1:40456";

if (channel == null || !(channel.startsWith("aeron:") || channel.startsWith("aeron-spy:"))) {
    throw new ConfigException("channel must start with aeron: : " + channel);
}

try {
    ChannelUri uri = ChannelUri.parse(channel);
} catch (IllegalArgumentException e) {
    channel = "aeron:" + channel; // or fail fast with a clear message
}

When it happens

Trigger: Calling ChannelUri.parse with a string missing 'aeron:' — e.g. bare 'udp://host:port', 'localhost:40456', an empty/whitespace string, or a typo like 'aeron-udp:'.

Common situations: Reusing socket-style URIs from other libraries; concatenating transport onto the URI in the wrong place; config where the scheme got stripped by a properties loader; users writing 'aeron=udp://...' instead of 'aeron:udp://...'.

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

• URI length ( ) exceeds max supported length ( )…
• encountered ' ' within media definition at index in
• invalid prefix
• mediaReceiveTimestampOffset must be a number or the value
• channelReceiveTimestampOffset must be a number or the value

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

Appendix: source

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

            throw new IllegalArgumentException("URI length (" + length + ") exceeds max supported length (" +
                MAX_URI_LENGTH + "): " + uri.subSequence(0, MAX_URI_LENGTH));
        }

        int position = 0;
        final String prefix;
        if (startsWith(uri, 0, SPY_PREFIX))
        {
            prefix = SPY_QUALIFIER;
            position = SPY_PREFIX.length();
        }
        else
        {
            prefix = "";
        }

        if (!startsWith(uri, position, AERON_PREFIX))
        {
            throw new IllegalArgumentException("Aeron URIs must start with 'aeron:', found: " + uri);
        }
        else
        {
            position += AERON_PREFIX.length();
        }

        final StringBuilder builder = new StringBuilder();
        final Object2ObjectHashMap<String, String> params = new Object2ObjectHashMap<>();
        String media = null;
        String key = null;

        State state = State.MEDIA;
        for (int i = position; i < length; i++)
        {
            final char c = uri.charAt(i);
            switch (state)
            {
                case MEDIA:

View on GitHub (pinned to 6d60124e15)