{"record":{"id":"e54d281928ce9ffa","repo":"apache/cassandra","slug":"failed-to-bind-port-d-on-s","errorCode":null,"errorMessage":"Failed to bind port %d on %s.","messagePattern":"Failed to bind port (.+?) on (.+?)\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/transport/Server.java","lineNumber":153,"sourceCode":"    {\n         if (isRunning.compareAndSet(true, false))\n             close(force);\n    }\n\n    public boolean isRunning()\n    {\n        return isRunning.get();\n    }\n\n    public synchronized void start()\n    {\n        if(isRunning())\n            return;\n\n        // Configure the server.\n        ChannelFuture bindFuture = pipelineConfigurator.initializeChannel(workerGroup, socket, connectionFactory);\n        if (!bindFuture.awaitUninterruptibly().isSuccess())\n            throw new IllegalStateException(String.format(\"Failed to bind port %d on %s.\", socket.getPort(), socket.getAddress().getHostAddress()),\n                                            bindFuture.cause());\n\n        connectionTracker.allChannels.add(bindFuture.channel());\n        isRunning.set(true);\n    }\n\n    public int countConnectedClients()\n    {\n        return connectionTracker.countConnectedClients();\n    }\n\n    public Map<String, Integer> countConnectedClientsByUser()\n    {\n        return connectionTracker.countConnectedClientsByUser();\n    }\n\n    /**\n     * @return A count of the number of clients matching the given predicate.","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/transport/Server.java#L135-L171","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check what holds the port (netstat/lsof) and stop the conflicting process or change native_transport_port in cassandra.yaml","Verify native_transport_address / broadcast_address is an address actually assigned to the host","Look at the chained cause (bindFuture.cause()) for the exact errno (Address already in use, Cannot assign requested address, permission denied)","In containers/K8s, confirm port mappings and that the pod IP matches the configured bind address"],"exampleFix":"// before (cassandra.yaml)\nnative_transport_port: 9042   # already used by another node\n// after\nnative_transport_port: 9043","handlingStrategy":"try-catch","validationCode":"try (ServerSocket probe = new ServerSocket()) {\n    probe.bind(new InetSocketAddress(bindAddr, port)); // throws if port unavailable\n} catch (IOException e) { throw new IllegalStateException(\"port \" + port + \" unavailable on \" + bindAddr, e); }","typeGuard":null,"tryCatchPattern":"try { server.start(); } catch (IllegalStateException e) { if (e.getMessage().startsWith(\"Failed to bind port\")) { logBindDiagnostics(e.getCause()); alternatePortOrAbort(); } else throw e; }","preventionTips":["Check port availability before startup with lsof/netstat","Avoid hardcoding ports in multi-node/container environments","Confirm bind address exists on the host before launch (ip addr)","Read the chained cause for the exact bind failure reason"],"tags":["network","bind","port-in-use","startup"],"backgroundTag":"address-already-in-use","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"}