{"record":{"id":"2c8b14d4c2ea9dfa","repo":"apache/incubator-seata","slug":"server-start-failed-the-listen-port-s","errorCode":null,"errorMessage":"Server start failed, the listen port: %s","messagePattern":"Server start failed, the listen port: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/apache/seata/core/rpc/netty/NettyServerBootstrap.java","lineNumber":207,"sourceCode":"                                    new HttpDetector()\n                                }));\n                    }\n                });\n\n        try {\n            this.serverBootstrap.bind(port).sync();\n            LOGGER.info(\"Server started, service listen port: {}\", getListenPort());\n            Instance instance = Instance.getInstance();\n            // Lines 177-180 are just for compatibility with test cases\n            if (instance.getTransaction() == null) {\n                Instance.getInstance().setTransaction(new Node.Endpoint(XID.getIpAddress(), XID.getPort(), \"netty\"));\n            }\n            for (RegistryService<?> registryService : MultiRegistryFactory.getInstances()) {\n                registryService.register(Instance.getInstance());\n            }\n            initialized.set(true);\n        } catch (SocketException se) {\n            throw new RuntimeException(\"Server start failed, the listen port: \" + getListenPort(), se);\n        } catch (Exception exx) {\n            throw new RuntimeException(\"Server start failed\", exx);\n        }\n    }\n\n    @Override\n    public void shutdown() {\n        try {\n            if (LOGGER.isInfoEnabled()) {\n                LOGGER.info(\"Shutting server down, the listen port: {}\", getListenPort());\n            }\n            if (initialized.get()) {\n                for (RegistryService registryService : MultiRegistryFactory.getInstances()) {\n                    registryService.unregister(Instance.getInstance());\n                    registryService.close();\n                }\n                // wait a few seconds for server transport\n                TimeUnit.SECONDS.sleep(nettyServerConfig.getServerShutdownWaitTime());","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/rpc/netty/NettyServerBootstrap.java#L189-L225","documentation":"Thrown by NettyServerBootstrap when the Seata Server's Netty listener fails to bind its service port and the underlying cause is a java.net.SocketException. The listen port is included in the message so you can identify which endpoint failed. The original SocketException is chained as the cause. This is a fatal startup error: the server cannot accept transaction coordination traffic until the port is free.","triggerScenarios":"serverBootstrap.bind(port).sync() throws SocketException: the configured service listen port (e.g. 8091, from service.port / netty port config) is already in use by another process, or the OS refused the bind (insufficient permissions for a privileged port, address already in use after an unclean shutdown, or the port is taken by another Seata instance).","commonSituations":"Running two Seata Server instances (or a leftover process from a previous run) on the same port; a previous server process still holding the port in TIME_WAIT; running in a container where the port was mapped/occupied; CI environments starting the server twice in parallel.","solutions":["Find and stop the process occupying the port: `netstat -tlnp | grep <port>` or `lsof -i :<port>`, then kill it or wait for TIME_WAIT to clear.","If a second server is intentional, change the listen port (e.g. server.servicePort / store config 8091 -> 8092) for one instance.","If binding a privileged port (<1024) without root, switch to an unprivileged port or grant the JVM the needed capability.","Inspect the chained cause (RuntimeException.getCause()) to confirm it is 'Address already in use' versus a permission-denied SocketException, and fix accordingly."],"exampleFix":"// before: two instances both on 8091\n# instance A\nsh seata-server.sh -p 8091\n# instance B on same host\nsh seata-server.sh -p 8091   # -> Server start failed, the listen port: 8091\n\n// after\n# instance B\nsh seata-server.sh -p 8092","handlingStrategy":"validation","validationCode":"// before starting Seata server in-process / embedding it\ntry (java.net.ServerSocket probe = new java.net.ServerSocket(port)) {\n    // port is free\n} catch (java.net.BindException e) {\n    throw new IllegalStateException(\"Port \" + port + \" already in use - pick another or stop the occupant\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    nettyServerBootstrap.start();\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof java.net.SocketException) {\n        // port-level failure: report port, check occupancy, choose new port and retry once\n    }\n    throw e;\n}","preventionTips":["Reserve the Seata service port per host and document it; never run two servers on one host without distinct ports.","Add a startup port-free check (ServerSocket probe) to deployment scripts.","Use systemd/k8s liveness so a zombie seata-server from a previous deploy cannot hold the port."],"tags":["network","netty","port-bind","startup","server"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}