apache/cassandra · critical · IllegalStateException

Failed to bind port on .

Error message

Failed to bind port %d on %s.

What it means

Thrown when the native transport server fails to bind its listening socket during start(). The Netty bind future completes unsuccessfully (port in use, address not available, permission denied), and the code wraps the underlying cause in an IllegalStateException naming the port and address. The server does not start and the transport is unavailable.

Solutions

1. Check what holds the port (netstat/lsof) and stop the conflicting process or change native_transport_port in cassandra.yaml
2. Verify native_transport_address / broadcast_address is an address actually assigned to the host
3. Look at the chained cause (bindFuture.cause()) for the exact errno (Address already in use, Cannot assign requested address, permission denied)
4. In containers/K8s, confirm port mappings and that the pod IP matches the configured bind address

Example fix

// before (cassandra.yaml)
native_transport_port: 9042   # already used by another node
// after
native_transport_port: 9043

try (ServerSocket probe = new ServerSocket()) {
    probe.bind(new InetSocketAddress(bindAddr, port)); // throws if port unavailable
} catch (IOException e) { throw new IllegalStateException("port " + port + " unavailable on " + bindAddr, e); }

try { server.start(); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Failed to bind port")) { logBindDiagnostics(e.getCause()); alternatePortOrAbort(); } else throw e; }

When it happens

Trigger: Server.start() is called and pipelineConfigurator.initializeChannel(...)'s ChannelFuture completes unsuccessfully after awaitUninterruptibly(); e.g. another process already listens on the port, the configured bind address does not exist on the host, or a privileged port is used without permissions.

Common situations: Two Cassandra instances on one machine both binding 9042, stale process holding the port, cassandra.yaml native_transport_address set to an IP not present on the host, container networking misconfiguration, or binding to port <1024 as non-root.

Related errors

• is in use by another process. Change…
• Configured " " could not be found
• Configured " " was found, but had no addresses
• Could not discover CMS from
• failed to bind to

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

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/Server.java:153

    {
         if (isRunning.compareAndSet(true, false))
             close(force);
    }

    public boolean isRunning()
    {
        return isRunning.get();
    }

    public synchronized void start()
    {
        if(isRunning())
            return;

        // Configure the server.
        ChannelFuture bindFuture = pipelineConfigurator.initializeChannel(workerGroup, socket, connectionFactory);
        if (!bindFuture.awaitUninterruptibly().isSuccess())
            throw new IllegalStateException(String.format("Failed to bind port %d on %s.", socket.getPort(), socket.getAddress().getHostAddress()),
                                            bindFuture.cause());

        connectionTracker.allChannels.add(bindFuture.channel());
        isRunning.set(true);
    }

    public int countConnectedClients()
    {
        return connectionTracker.countConnectedClients();
    }

    public Map<String, Integer> countConnectedClientsByUser()
    {
        return connectionTracker.countConnectedClientsByUser();
    }

    /**
     * @return A count of the number of clients matching the given predicate.

View on GitHub (pinned to 88fd0f6a0e)