aeron-io/aeron · error · IllegalArgumentException

invalid prefix

Error message

invalid prefix: ${prefix}

What it means

Thrown by ChannelUriStringBuilder.prefix(String) when a non-empty prefix other than the spy qualifier is supplied. Aeron only supports 'aeron:' (implicit) and the 'aeron-spy:' prefix; anything else cannot form a valid channel URI.

Solutions

1. Use prefix("aeron-spy:") only when spy semantics are intended; otherwise omit prefix entirely.
2. Move transport selection to media("udp") or media("ipc").
3. Strip or normalize the prefix before building if you received a full URI string.

Example fix

// before
builder.prefix("udp:").media("udp");
// after
builder.media("udp");

if (prefix != null && !prefix.isEmpty() && !ChannelUri.SPY_QUALIFIER.equals(prefix)) { throw new IllegalArgumentException("invalid prefix: " + prefix); }

boolean isValidPrefix(String prefix) { return prefix == null || prefix.isEmpty() || ChannelUri.SPY_QUALIFIER.equals(prefix); }

try { builder.prefix(p); } catch (IllegalArgumentException e) { builder.prefix(null); /* fall back to default */ }

When it happens

Trigger: builder.prefix("udp:") or any string other than "aeron-spy:" (ChannelUri.SPY_QUALIFIER) or null/empty.

Common situations: Trying to encode the transport in the prefix instead of media(); typo of the spy qualifier (e.g. "aeron-spy" without colon or "spy:"); carrying over a URI fragment parsed from another system.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• URI length ( ) exceeds max supported length ( )…
• Aeron URIs must start with 'aeron:', found
• encountered ' ' within media definition at index in
• unknown media
• difference greater than 2^31 - 1: termId=

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

Appendix: source

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

                throw new IllegalArgumentException("termOffset=" + termOffset + " > termLength=" + termLength);
            }
        }

        return this;
    }

    /**
     * Set the prefix for taking an additional action such as spying on an outgoing publication with "aeron-spy".
     *
     * @param prefix to be applied to the URI before the scheme.
     * @return this for a fluent API.
     * @see ChannelUri#SPY_QUALIFIER
     */
    public ChannelUriStringBuilder prefix(final String prefix)
    {
        if (null != prefix && !prefix.isEmpty() && !prefix.equals(SPY_QUALIFIER))
        {
            throw new IllegalArgumentException("invalid prefix: " + prefix);
        }

        this.prefix = prefix;
        return this;
    }

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

View on GitHub (pinned to 6d60124e15)