aeron-io/aeron · error · InvalidChannelException

invalid channel

Error message

invalid channel: ${ex}

What it means

ChannelUri.parse failed to parse the given channel URI string, so the driver wraps the underlying exception in InvalidChannelException and reports the channel as invalid. Aeron channel URIs must follow the aeron: transport schema with valid params (e.g. aeron:udp?endpoint=host:port). Malformed syntax, unknown transport, or illegal parameters make the subscription/publication request unprocessable.

Solutions

  1. Validate the URI with ChannelUri.parse(channel) in a try/catch before sending the request to the driver
  2. Use ChannelUriStringBuilder to construct channels instead of hand-built strings
  3. Print/log the exact channel string passed to addSubscription/addPublication and check prefix is 'aeron:udp' or 'aeron:ipc'
  4. Catch InvalidChannelException around client add* calls and surface a clear config error to the operator

Example fix

// before
String channel = "aeron:udp?endpoint=" + host + ":"; // port missing -> InvalidChannelException
subscription = aeron.addSubscription(channel, streamId);
// after
String channel = new ChannelUriStringBuilder()
    .media("udp").endpoint(host + ":" + port).build();
subscription = aeron.addSubscription(channel, streamId);
Defensive patterns

Strategy: validation

Validate before calling

try
{
    ChannelUri.parse(channel);
}
catch (Exception ex)
{
    throw new IllegalArgumentException("Bad channel URI: " + channel, ex);
}

Type guard

static boolean isValidChannel(String channel)
{
    try { ChannelUri.parse(channel); return true; }
    catch (Exception ex) { return false; }
}

Try / catch

try
{
    subscription = aeron.addSubscription(channel, streamId);
}
catch (InvalidChannelException ex)
{
    log.error("Invalid channel URI '{}': {}", channel, ex.getMessage());
}

Prevention

When it happens

Trigger: Adding a subscription or publication with a malformed channel string such as missing 'aeron:udp'/'aeron:ipc' prefix, unbalanced quoting, bad endpoint syntax, or unknown params that the URI parser rejects; parse happens in DriverConductor when validating the channel before creating the endpoint.

Common situations: Typo in channel URI (e.g. 'aeron:up?...' or missing '?'); building the URI by string concatenation with a null or empty host/port; copying a URI from docs with placeholders left in; platform-specific multicast address typos.

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/751fef1416af05e7. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java:1219

                }
            }
        }
        else
        {
            timeOfLastToDriverPositionChangeNs = nowNs;
            lastCommandConsumerPosition = consumerPosition;
        }
    }

    private static ChannelUri parseUri(final String channel)
    {
        try
        {
            return ChannelUri.parse(channel);
        }
        catch (final Exception ex)
        {
            throw new InvalidChannelException(ex);
        }
    }

    private record StreamInterest(boolean sparse, boolean reliable, boolean multicastSemantics)
    {
    }

    private StreamInterest findSubscribers(
        final ReceiveChannelEndpoint channelEndpoint, final int sessionId, final int streamId, final short flags)
    {
        if (ChannelEndpointStatus.ACTIVE != channelEndpoint.status())
        {
            return null;
        }

        long regId = Long.MAX_VALUE;
        boolean hasSubscribers = false;
        boolean sparse = false, reliable = false, multicastSemantics = false;

View on GitHub (pinned to 6d60124e15)