{"record":{"id":"5d38d26bee9a237a","repo":"apache/cassandra","slug":"failed-to-bind-to-bind","errorCode":null,"errorMessage":"failed to bind to: <bind>","messagePattern":"failed to bind to: <bind>","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/net/InboundConnectionInitiator.java","lineNumber":209,"sourceCode":"            Throwable failedChannelCause = channelFuture.cause();\n\n            String causeString = \"\";\n            if (failedChannelCause != null && failedChannelCause.getMessage() != null)\n                causeString = failedChannelCause.getMessage();\n\n            if (causeString.contains(\"in use\"))\n            {\n                throw new ConfigurationException(bind + \" is in use by another process.  Change listen_address:storage_port \" +\n                                                 \"in cassandra.yaml to values that do not conflict with other services\");\n            }\n            else if (causeString.contains(\"cannot assign requested address\"))\n            {\n                throw new ConfigurationException(\"Unable to bind to address \" + bind\n                                                 + \". Set listen_address in cassandra.yaml to an interface you can bind to, e.g., your private IP address on EC2\");\n            }\n            else\n            {\n                throw new ConfigurationException(\"failed to bind to: \" + bind, failedChannelCause);\n            }\n        }\n\n        return channelFuture;\n    }\n\n    public static ChannelFuture bind(InboundConnectionSettings settings, ChannelGroup channelGroup,\n                                     Consumer<ChannelPipeline> pipelineInjector)\n    {\n        return bind(new Initializer(settings, channelGroup, pipelineInjector));\n    }\n\n    /**\n     * Handler to perform authentication for internode inbound connections.\n     * This handler is called even before messaging handshake starts.\n     */\n    private static class ClientAuthenticationHandler extends ByteToMessageDecoder\n    {","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/net/InboundConnectionInitiator.java#L191-L227","documentation":"The fallback branch of InboundConnectionInitiator.bind(): any Netty bind failure whose message matches neither 'in use' nor 'cannot assign requested address' is rethrown as a generic ConfigurationException 'failed to bind to: <bind>' with the original cause attached.","triggerScenarios":"bind() fails for reasons other than port-in-use or unassigned address — e.g. permission denied on privileged ports, security modules blocking socket creation, or other unexpected bind errors.","commonSituations":"Binding a port below 1024 as a non-root user; SELinux/AppArmor/seccomp policies blocking socket creation in containers; unusual platform-specific bind errors.","solutions":["Inspect the wrapped cause (failedChannelCause) for the underlying errno (e.g. permission denied)","Avoid privileged ports; use a storage_port >= 1024 in cassandra.yaml","Check that the process has permission to create sockets in the environment (container seccomp/AppArmor, SELinux)","If persistent, escalate with the full 'Caused by' stack trace from the log"],"exampleFix":"// before: only seeing 'failed to bind to: /10.0.0.5:7000'\n// after: read the 'Caused by:' line in the log, e.g. java.net.SocketException: permission denied, and fix storage_port/permissions accordingly","handlingStrategy":"try-catch","validationCode":"// ensure the storage port is >= 1024 and the process can bind\nif (DatabaseDescriptor.getStoragePort() < 1024 && !runningAsRoot)\n    throw new IllegalStateException(\"privileged port requires root or CAP_NET_BIND_SERVICE\");","typeGuard":null,"tryCatchPattern":"try { startCassandra(); } catch (ConfigurationException e) { log.error(\"bind failed\", e.getCause()); /* inspect the wrapped cause for the real errno */ }","preventionTips":["Always log and read the cause chained to this ConfigurationException","Avoid storage ports below 1024 for non-root processes","Check SELinux/AppArmor/seccomp policies that may block socket creation","Test bind permissions in the target container image before production rollout"],"tags":["network","bind","configuration"],"backgroundTag":"http-request-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}