aeron-io/aeron · error · IllegalArgumentException

URI length ( ) exceeds max supported length ( )…

Error message

URI length (<length>) exceeds max supported length (<MAX_URI_LENGTH>): <uri-prefix>

What it means

ChannelUri.parse rejects any Aeron URI longer than MAX_URI_LENGTH, throwing IllegalArgumentException that includes the length, the max, and a prefix of the offending URI. URIs are stored in fixed-size structures (e.g. sent in subscription/publication setup and stored in the driver), so a hard cap is enforced.

Solutions

  1. Check uri.length() against ChannelUri.MAX_URI_LENGTH before parsing and trim/simplify the channel config.
  2. Shorten the URI: remove unneeded parameters, use shorter endpoint names, or move options to configuration instead of the URI.
  3. If the URI comes from external input, validate the length at ingestion with a clear error message.

Example fix

// before
ChannelUri uri = ChannelUri.parse(userSuppliedUri);
// after
if (userSuppliedUri.length() > ChannelUri.MAX_URI_LENGTH) {
    throw new ConfigException("channel URI too long (max " + ChannelUri.MAX_URI_LENGTH + ")");
}
ChannelUri uri = ChannelUri.parse(userSuppliedUri);
Defensive patterns

Strategy: validation

Validate before calling

if (channelUri == null || channelUri.length() > ChannelUri.MAX_URI_LENGTH) {
    throw new ConfigException("channel URI missing or longer than " + ChannelUri.MAX_URI_LENGTH);
}

Try / catch

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

Prevention

When it happens

Trigger: Calling ChannelUri.parse(uri) where uri.length() > MAX_URI_LENGTH — e.g. a channel string with very long endpoint names, embedded credentials, or concatenated control/properties.

Common situations: Programmatically building URIs with many parameters and never length-checking; hostnames/IPs plus options pushing past the limit; a corrupted or malicious channel string from external input.

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/276a09507e38ffe1. Report an issue: GitHub.

Appendix: source

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

        put(INITIAL_TERM_ID_PARAM_NAME, Integer.toString(initialTermId));
        put(TERM_ID_PARAM_NAME, Integer.toString(termId));
        put(TERM_OFFSET_PARAM_NAME, Integer.toString(termOffset));
        put(TERM_LENGTH_PARAM_NAME, Integer.toString(termLength));
    }

    /**
     * Parse a {@link CharSequence} which contains an Aeron URI.
     *
     * @param uri to be parsed.
     * @return a new {@link ChannelUri} representing the URI string.
     */
    @SuppressWarnings("MethodLength")
    public static ChannelUri parse(final CharSequence uri)
    {
        final int length = uri.length();
        if (length > MAX_URI_LENGTH)
        {
            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);

View on GitHub (pinned to 6d60124e15)