aeron-io/aeron · error · IllegalArgumentException

has port=0 for publication: channel=

Error message

${ENDPOINT_PARAM_NAME} has port=0 for publication: channel=${originalUriString}

What it means

For publications, the 'endpoint' parameter must include a non-zero port: port 0 is only valid for the OS to pick a port on a server-side bind, which makes no sense for a data destination. The driver throws this IllegalArgumentException during channel validation when a non-multi-destination publication specifies an endpoint with port 0.

Solutions

Set an explicit non-zero port in endpoint=host:port
Fix configuration so the port value is populated before constructing the URI
Validate the URI client-side before calling addPublication

Example fix

// before
aeron.addPublication("aeron:udp?endpoint=localhost:0", 1001);
// after
aeron.addPublication("aeron:udp?endpoint=localhost:40456", 1001);

Defensive patterns

Strategy: validation

Validate before calling

int port = uriEndpointPort(channel);
if (port == 0) throw new IllegalArgumentException("publication endpoint port must be non-zero: " + channel);

Try / catch

try { aeron.addPublication(channel, streamId); } catch (IllegalArgumentException e) { if (e.getMessage().contains("has port=0")) { log.error("fix endpoint port in {}", channel); } throw e; }

Prevention

Fail fast on port==0 in URI-building code for publications
Validate config-provided ports are in 1..65535 at startup
Never reuse subscription-style wildcard port patterns for publications

When it happens

Trigger: Aeron.addPublication with "aeron:udp?endpoint=host:0" (or an omitted port parsing to 0) on a non-MDC publication; programmatically built URIs where the port variable defaulted to 0.

Common situations: Placeholder port not filled in from config; missing-env-var style bug where port config is absent and defaults to 0; mistaking subscription-style wildcard port usage as valid for publications.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

        final int existingLength,
        final String channel,
        final String existingChannel)
    {
        if (0 != newLength && newLength != existingLength)
        {
            final Object existingValue = 0 == existingLength ? "OS default" : existingLength;
            throw new InvalidChannelException(
                paramName + "=" + newLength + " does not match existing value of " + existingValue +
                    ": existingChannel=" + existingChannel + " channel=" + channel);
        }
    }

    private static void validateEndpointForPublication(final UdpChannel udpChannel)
    {
        if (!udpChannel.isMultiDestination() && udpChannel.hasExplicitEndpoint() &&
            0 == udpChannel.remoteData().getPort())
        {
            throw new IllegalArgumentException(
                ENDPOINT_PARAM_NAME + " has port=0 for publication: channel=" + udpChannel.originalUriString());
        }
    }

    private static void validateControlForPublication(final UdpChannel udpChannel)
    {
        if (udpChannel.isDynamicControlMode() && !udpChannel.hasExplicitControl())
        {
            throw new IllegalArgumentException(
                "'control-mode=dynamic' requires that 'control' parameter is set, channel=" +
                    udpChannel.originalUriString());
        }

        if (udpChannel.hasExplicitControl() && !udpChannel.hasExplicitEndpoint() &&
            ControlMode.NONE == udpChannel.controlMode())
        {
            throw new IllegalArgumentException(
                "'control' parameter requires that either 'endpoint' or 'control-mode' is specified, channel=" +

View on GitHub (pinned to 6d60124e15)