aeron-io/aeron · error · AeronException

channel error -

Error message

channel error - 

What it means

openDatagramChannel failed while creating/binding the UDP datagram socket for the channel. The underlying IOException message, the top stack frame, and the original channel URI are wrapped into an AeronException ('channel error - ...') so the operator can see exactly where socket setup failed.

Solutions

1. Read the embedded IOException and stack frame: if 'Address already in use', free the port or choose another.
2. Verify the localAddress/interface parameters in the channel URI are valid and available on the host.
3. Run with sufficient privileges or move to an unprivileged port (>1024).
4. Check OS limits (ulimit -n, ephemeral port range) and firewall/SELinux policy.

Example fix

// before
"aeron:udp?endpoint=0.0.0.0:40456|interface=lo:40456" // lo already bound by another driver
// after
"aeron:udp?endpoint=0.0.0.0:40456|interface=eth0:40456" // or stop the conflicting process

// Pre-check the bind address before opening the channel
try (DatagramChannel ch = DatagramChannel.open()) {
    ch.bind(new InetSocketAddress(localPort)); ch.close();
} catch (IOException e) { /* port unavailable — pick another */ }

try {
    transport.openDatagramChannel(statusIndicator);
} catch (AeronException e) {
    if (e.getMessage().contains("channel error")) {
        logger.error("socket setup failed: {}", e.getMessage());
        // check port conflicts / permissions before retry
    }
}

When it happens

Trigger: Opening a UdpChannelTransport when DatagramChannel.open/bind fails: address already in use, permission denied for privileged ports, invalid local address/interface, or OS socket limits reached.

Common situations: Two drivers binding the same port (address already in use), binding port <1024 as non-root, wrong interface name/address in the URI, firewall/SELinux blocking socket ops, or exhausted ephemeral ports/file descriptors.

Related errors

• could not resolve control address:
• could not resolve endpoint address:
• exceeded session limit, streamId=
• failed get replay image for sessionId=" +…
• re-resolve endpoint channel error -

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/UdpChannelTransport.java:276

        {
            if (null != statusIndicator)
            {
                statusIndicator.setRelease(ChannelEndpointStatus.ERRORED);
            }

            CloseHelper.quietClose(sendDatagramChannel);
            if (receiveDatagramChannel != sendDatagramChannel)
            {
                CloseHelper.quietClose(receiveDatagramChannel);
            }

            sendDatagramChannel = null;
            receiveDatagramChannel = null;

            final String message = "channel error - " + ex.getMessage() +
                " (at " + ex.getStackTrace()[0].toString() + "): " + udpChannel.originalUriString();

            throw new AeronException(message, ex);
        }
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void close()
    {
        CloseHelper.close(errorHandler, sendDatagramChannel);
        if (receiveDatagramChannel != sendDatagramChannel)
        {
            CloseHelper.close(errorHandler, receiveDatagramChannel);
        }
        portManager.freeManagedPort(bindAddress);
    }

    /**

View on GitHub (pinned to 6d60124e15)