{"record":{"id":"52c7def315046c1f","repo":"aeron-io/aeron","slug":"channel-error","errorCode":null,"errorMessage":"channel error - ","messagePattern":"channel error - ","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannelTransport.java","lineNumber":276,"sourceCode":"        {\n            if (null != statusIndicator)\n            {\n                statusIndicator.setRelease(ChannelEndpointStatus.ERRORED);\n            }\n\n            CloseHelper.quietClose(sendDatagramChannel);\n            if (receiveDatagramChannel != sendDatagramChannel)\n            {\n                CloseHelper.quietClose(receiveDatagramChannel);\n            }\n\n            sendDatagramChannel = null;\n            receiveDatagramChannel = null;\n\n            final String message = \"channel error - \" + ex.getMessage() +\n                \" (at \" + ex.getStackTrace()[0].toString() + \"): \" + udpChannel.originalUriString();\n\n            throw new AeronException(message, ex);\n        }\n    }\n\n    /**\n     * {@inheritDoc}\n     */\n    @Override\n    public void close()\n    {\n        CloseHelper.close(errorHandler, sendDatagramChannel);\n        if (receiveDatagramChannel != sendDatagramChannel)\n        {\n            CloseHelper.close(errorHandler, receiveDatagramChannel);\n        }\n        portManager.freeManagedPort(bindAddress);\n    }\n\n    /**","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannelTransport.java#L258-L294","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the embedded IOException and stack frame: if 'Address already in use', free the port or choose another.","Verify the localAddress/interface parameters in the channel URI are valid and available on the host.","Run with sufficient privileges or move to an unprivileged port (>1024).","Check OS limits (ulimit -n, ephemeral port range) and firewall/SELinux policy."],"exampleFix":"// before\n\"aeron:udp?endpoint=0.0.0.0:40456|interface=lo:40456\" // lo already bound by another driver\n// after\n\"aeron:udp?endpoint=0.0.0.0:40456|interface=eth0:40456\" // or stop the conflicting process","handlingStrategy":"try-catch","validationCode":"// Pre-check the bind address before opening the channel\ntry (DatagramChannel ch = DatagramChannel.open()) {\n    ch.bind(new InetSocketAddress(localPort)); ch.close();\n} catch (IOException e) { /* port unavailable — pick another */ }","typeGuard":null,"tryCatchPattern":"try {\n    transport.openDatagramChannel(statusIndicator);\n} catch (AeronException e) {\n    if (e.getMessage().contains(\"channel error\")) {\n        logger.error(\"socket setup failed: {}\", e.getMessage());\n        // check port conflicts / permissions before retry\n    }\n}","preventionTips":["Use SO_REUSEADDR-style planning: unique ports per driver","Run drivers as users permitted to bind chosen ports","Check ulimit and firewall rules in deployment scripts","Log originalUriString on failure (already included) for triage"],"tags":["network","udp","socket","bind"],"backgroundTag":"address-already-in-use","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}