aeron-io/aeron · error · InvalidChannelException

InvalidChannelException

Error message

InvalidChannelException

What it means

A wrapper exception (InvalidChannelException) thrown from UdpChannel.parse for ANY exception raised while parsing or validating a channel URI, including address resolution failures and invalid parameters. The original cause is available via getCause().

Solutions

1. Inspect ex.getCause() to find the underlying parse error
2. Validate the channel URI syntax (aeron:udp?param=value) before passing it to Aeron
3. Check parameter names against the Aeron version in use
4. Fix the specific root cause (hostname, numeric value, tag configuration)

Example fix

// before
client.addSubscription(uri, streamId); // uri malformed, NPE wraps into InvalidChannelException
// after
if (uri == null || !uri.startsWith("aeron:")) throw new IllegalArgumentException("bad channel: " + uri);
client.addSubscription(uri, streamId);

if (!uri.startsWith("aeron:udp") && !uri.startsWith("aeron:ipc")) throw new IllegalArgumentException("unsupported channel: " + uri);

static boolean isWellFormedAeronUri(String uri) { return uri != null && uri.matches("aeron:(udp|ipc)(\\?.*)?"); }

try { return aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { throw new IllegalArgumentException("bad channel URI '" + uri + "': " + e.getCause().getMessage(), e); }

When it happens

Trigger: Any malformed or unresolvable channel URI passed to addSubscription/addPublication, e.g. unknown parameter names, unparseable addresses, invalid tags or control-mode combos.

Common situations: Mistyped channel URIs in configuration, dynamic channel construction from user input, version upgrades adding new parameter validation, unresolvable hostnames.

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

• destinations must not contain the key
• difference greater than 2^31 - 1: termId=
• invalid control mode
• invalid maxResend= , must be > 0 and <=
• invalid media

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java:298

                    .remoteDataAddress(endpointAddress)
                    .localControlAddress(localAddress)
                    .localDataAddress(localAddress)
                    .canonicalForm(canonicalise(null, localAddress, endpointVal, endpointAddress) + suffix);
            }

            context.channelReceiveTimestampOffset(
                parseTimestampOffset(channelUri, CHANNEL_RECEIVE_TIMESTAMP_OFFSET_PARAM_NAME));
            context.channelSendTimestampOffset(
                parseTimestampOffset(channelUri, CHANNEL_SEND_TIMESTAMP_OFFSET_PARAM_NAME));

            final Long groupTag = parseOptionalLong(channelUri, GROUP_TAG_PARAM_NAME);
            context.groupTag(groupTag);

            return new UdpChannel(context);
        }
        catch (final Exception ex)
        {
            throw new InvalidChannelException(ex);
        }
    }

    private static int parseTimestampOffset(final ChannelUri channelUri, final String timestampOffsetParamName)
    {
        final String offsetStr = channelUri.get(timestampOffsetParamName);
        if (null == offsetStr)
        {
            return Aeron.NULL_VALUE;
        }
        else if (RESERVED_OFFSET.equals(offsetStr))
        {
            return RESERVED_VALUE_MESSAGE_OFFSET;
        }
        else
        {
            try
            {

View on GitHub (pinned to 6d60124e15)