apache/cassandra · critical · ConfigurationException

Unable to bind to address

Error message

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

What it means

InboundConnectionInitiator.bind() translates Netty bind failures: when the OS reports 'cannot assign requested address', Cassandra cannot bind to the configured listen_address at all — the address is not assigned to any local interface. A ConfigurationException advising to set listen_address to a bindable interface is thrown.

Solutions

1. Set listen_address to a local private IP or 0.0.0.0 in cassandra.yaml, or use listen_interface instead
2. Verify the address exists on the host (ip addr show) and pick one actually assigned
3. On EC2, use the private IP or listen_interface: eth0 instead of the public IP
4. If using a hostname, confirm it resolves to a local address (getent hosts <hostname>)

Example fix

// before (cassandra.yaml)
listen_address: 54.12.34.56  # EC2 public IP, not bound to NIC
// after
listen_interface: eth0

// verify listen_address is locally bound before starting
InetAddress addr = InetAddress.getByName(FBUtilities.getBroadcastAddressAndPort().getAddressString());
if (!addr.isAnyLocalAddress() && NetworkInterface.getByInetAddress(addr) == null)
    throw new IllegalStateException("listen_address not assigned to any local interface");

try { startCassandra(); } catch (ConfigurationException e) { if (e.getMessage().contains("Unable to bind to address")) { /* fix listen_address to a local interface */ } }

When it happens

Trigger: bind() called with a listen_address that does not exist on the host (typo, stale EC2 public IP, hostname resolving to a non-local IP).

Common situations: Setting listen_address to an EC2 public IP (not bound to the NIC); hostname resolution changes after restart; copied cassandra.yaml from another machine; interface renamed or DHCP address changed.

Related errors

• is in use by another process. Change…
• failed to bind to
• broadcast_address cannot be a wildcard address (
• Failed to bind port on .
• Invalid ip address from input=

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

Appendix: source

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

        if (!channelFuture.awaitUninterruptibly().isSuccess())
        {
            if (channelFuture.channel().isOpen())
                channelFuture.channel().close();

            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));
    }

    /**

View on GitHub (pinned to 88fd0f6a0e)