{"record":{"id":"4f63e556f96b14bb","repo":"alibaba/nacos","slug":"fail-to-init-baserpcserver","errorCode":null,"errorMessage":"Fail to init [BaseRpcServer].","messagePattern":"Fail to init \\[BaseRpcServer\\]\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/com/alibaba/nacos/core/distributed/raft/JRaftServer.java","lineNumber":215,"sourceCode":"        if (!isStarted) {\n            Loggers.RAFT.info(\"========= The raft protocol is starting... =========\");\n            try {\n                // init raft group node\n                com.alipay.sofa.jraft.NodeManager raftNodeManager =\n                    com.alipay.sofa.jraft.NodeManager.getInstance();\n                for (String address : raftConfig.getMembers()) {\n                    PeerId peerId = PeerId.parsePeer(address);\n                    conf.addPeer(peerId);\n                    raftNodeManager.addAddress(peerId.getEndpoint());\n                }\n                nodeOptions.setInitialConf(conf);\n                \n                rpcServer = JRaftUtils.initRpcServer(this, localPeerId,\n                    jRaftAuthUpgradeCoordinator);\n                \n                if (!this.rpcServer.init(null)) {\n                    Loggers.RAFT.error(\"Fail to init [BaseRpcServer].\");\n                    throw new RuntimeException(\"Fail to init [BaseRpcServer].\");\n                }\n                \n                // Initialize multi raft group service framework\n                isStarted = true;\n                createMultiRaftGroup(processors);\n                Loggers.RAFT.info(\"========= The raft protocol start finished... =========\");\n            } catch (Exception e) {\n                Loggers.RAFT.error(\"raft protocol start failure, cause: \", e);\n                throw new JRaftException(e);\n            }\n        }\n    }\n    \n    synchronized void createMultiRaftGroup(Collection<RequestProcessor4CP> processors) {\n        // There is no reason why the LogProcessor cannot be processed because of the synchronization\n        if (!this.isStarted) {\n            this.processors.addAll(processors);\n            return;","sourceCodeStart":197,"sourceCodeEnd":233,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/core/src/main/java/com/alibaba/nacos/core/distributed/raft/JRaftServer.java#L197-L233","documentation":"Thrown during JRaftServer.start() when rpcServer.init(null) returns false, meaning the SOFA-JRaft BaseRpcServer failed to initialize (bind/listen). The raw RuntimeException is itself wrapped into a JRaftException by the surrounding catch. This aborts CP-protocol (Raft) startup on the node.","triggerScenarios":"The JRaft gRPC server endpoint (derived from the local PeerId / raft members) cannot bind — port already in use, address unavailable, or the local peer address is misconfigured. The init() returning false is the JRaft idiom for a low-level bind failure.","commonSituations":"Another process (or a previous Nacos instance) holds the raft port; the configured cluster member address for this node is wrong; network interface binding problem; insufficient permissions to bind the port.","solutions":["Check the RAFT logs just above this line (Loggers.RAFT.error) and the JRaftException cause for the bind failure detail.","Ensure the raft port (member address) is free: stop stale Nacos/JRaft processes or fix the address.","Verify nacos member/cluster.conf or the address server lists the correct, reachable address for this node.","Confirm the OS allows binding to the configured port (permissions/firewall)."],"exampleFix":"// before: two nodes configured with the same raft address\ncluster.conf:\n1.1.1.1:7848\n1.1.1.1:7848   # duplicate -> init() fails\n\n// after: distinct addresses\ncluster.conf:\n1.1.1.1:7848\n2.2.2.2:7848","handlingStrategy":"try-catch","validationCode":"// before starting, verify the raft port is free\ntry (ServerSocket s = new ServerSocket(raftPort)) { /* free */ }\ncatch (IOException e) { /* port in use — fix config before start */ }","typeGuard":null,"tryCatchPattern":"try {\n    jRaftServer.start();\n} catch (JRaftException e) {\n    Throwable c = e.getCause();\n    // inspect for BaseRpcServer init failure (port/address)\n}","preventionTips":["Ensure the raft/member port is free and unique per node.","Verify cluster.conf / address server lists correct addresses."],"tags":["raft","jraft","grpc","network","port-binding","startup","cp-protocol"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}