What causes "failed to bind to: " in apache/cassandra?

Inspect the wrapped cause (failedChannelCause) for the underlying errno (e.g. permission denied)

apache/cassandra · error · ConfigurationException

failed to bind to

Error message

failed to bind to: <bind>

What it means

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.

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

Example fix

// before: only seeing 'failed to bind to: /10.0.0.5:7000'
// after: read the 'Caused by:' line in the log, e.g. java.net.SocketException: permission denied, and fix storage_port/permissions accordingly

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure the storage port is >= 1024 and the process can bind
if (DatabaseDescriptor.getStoragePort() < 1024 && !runningAsRoot)
    throw new IllegalStateException("privileged port requires root or CAP_NET_BIND_SERVICE");

Try / catch

try { startCassandra(); } catch (ConfigurationException e) { log.error("bind failed", e.getCause()); /* inspect the wrapped cause for the real errno */ }

Prevention

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

When it happens

Trigger: 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.

Common situations: Binding a port below 1024 as a non-root user; SELinux/AppArmor/seccomp policies blocking socket creation in containers; unusual platform-specific bind errors.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/5d38d26bee9a237a. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/net/InboundConnectionInitiator.java:209

            Throwable failedChannelCause = channelFuture.cause();

            String causeString = "";
            if (failedChannelCause != null && failedChannelCause.getMessage() != null)
                causeString = failedChannelCause.getMessage();

            if (causeString.contains("in use"))
            {
                throw new ConfigurationException(bind + " is in use by another process.  Change listen_address:storage_port " +
                                                 "in cassandra.yaml to values that do not conflict with other services");
            }
            else if (causeString.contains("cannot assign requested address"))
            {
                throw new ConfigurationException("Unable to bind to address " + bind
                                                 + ". Set listen_address in cassandra.yaml to an interface you can bind to, e.g., your private IP address on EC2");
            }
            else
            {
                throw new ConfigurationException("failed to bind to: " + bind, failedChannelCause);
            }
        }

        return channelFuture;
    }

    public static ChannelFuture bind(InboundConnectionSettings settings, ChannelGroup channelGroup,
                                     Consumer<ChannelPipeline> pipelineInjector)
    {
        return bind(new Initializer(settings, channelGroup, pipelineInjector));
    }

    /**
     * Handler to perform authentication for internode inbound connections.
     * This handler is called even before messaging handshake starts.
     */
    private static class ClientAuthenticationHandler extends ByteToMessageDecoder
    {

View on GitHub (pinned to 88fd0f6a0e)