{"record":{"id":"057a74e4cec2042c","repo":"apache/incubator-seata","slug":"server-start-failed","errorCode":null,"errorMessage":"Server start failed","messagePattern":"Server start failed","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/apache/seata/core/rpc/netty/NettyServerBootstrap.java","lineNumber":209,"sourceCode":"                    }\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());\n            }\n","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/rpc/netty/NettyServerBootstrap.java#L191-L227","documentation":"The generic catch-all thrown by NettyServerBootstrap.start() when server startup fails with any exception other than SocketException — the bind itself may have succeeded, but a later step (XID initialization, instance endpoint setup, or registry registration) threw. The real reason is only in the chained cause, not the message. It aborts server startup entirely.","triggerScenarios":"The for-loop over MultiRegistryFactory.getInstances() calling registryService.register(...) fails — e.g. Nacos/Eureka/Redis/ZooKeeper registry unreachable, wrong registry address, auth failure — or Instance/XID endpoint setup throws, or any non-SocketException emerges from serverBootstrap.bind().sync().","commonSituations":"registry.type set to nacos/etcd3/consul but registry address points to a down or mis-authenticated registry cluster; registry namespace/group misconfigured so registration is rejected; partially configured file.conf/registry.conf after an upgrade; firewall blocking the registry port.","solutions":["Read the chained cause exception (exx) in the stack trace — it names the actual failing component (usually a specific RegistryService).","Verify registry connectivity from the server host: registry address, port, namespace, username/password (e.g. `curl http://<nacos>:8848/nacos`).","Fix registry.* keys in registry.conf / application.yml to match your registry cluster and restart.","If you do not want external registration, set registry.type=file to rule the registry out and retest startup.","Check XID network config (XID.getIpAddress/getPort) if the cause points at endpoint setup on multi-NIC hosts."],"exampleFix":"# before (registry.conf)\nregistry {\n  type = \"nacos\"\n  nacos {\n    serverAddr = \"nacos:8848\"   # wrong/unreachable -> Server start failed\n  }\n}\n\n# after\nregistry {\n  type = \"nacos\"\n  nacos {\n    serverAddr = \"10.0.0.5:8848\"\n    namespace = \"\"\n    username = \"nacos\"\n    password = \"nacos\"\n  }\n}","handlingStrategy":"try-catch","validationCode":"// verify registry reachability before starting the server (nacos example)\n// curl-equivalent in Java omitted; simplest: preflight with the registry client\n// Nacos: check /nacos/v1/console/health/liveness returns 200 before bootstrap","typeGuard":null,"tryCatchPattern":"try {\n    server.start();\n} catch (RuntimeException e) {\n    Throwable cause = e.getCause() != null ? e.getCause() : e;\n    log.error(\"seata server start failed, root cause: {}\", cause.toString());\n    // distinguish registry failure vs bind failure from the cause chain before retrying\n    throw e;\n}","preventionTips":["Always inspect the chained cause — the message 'Server start failed' alone is uninformative.","Smoke-test registry connectivity (address, credentials, namespace) as a pre-start health check.","Keep registry.conf/application.yml under version control and validate them in CI."],"tags":["startup","server","registry","nacos","configuration"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}