alibaba/nacos · critical · RuntimeException

Fail to init [BaseRpcServer].

Error message

Fail to init [BaseRpcServer].

What it means

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.

Source

Thrown at core/src/main/java/com/alibaba/nacos/core/distributed/raft/JRaftServer.java:215

        if (!isStarted) {
            Loggers.RAFT.info("========= The raft protocol is starting... =========");
            try {
                // init raft group node
                com.alipay.sofa.jraft.NodeManager raftNodeManager =
                    com.alipay.sofa.jraft.NodeManager.getInstance();
                for (String address : raftConfig.getMembers()) {
                    PeerId peerId = PeerId.parsePeer(address);
                    conf.addPeer(peerId);
                    raftNodeManager.addAddress(peerId.getEndpoint());
                }
                nodeOptions.setInitialConf(conf);
                
                rpcServer = JRaftUtils.initRpcServer(this, localPeerId,
                    jRaftAuthUpgradeCoordinator);
                
                if (!this.rpcServer.init(null)) {
                    Loggers.RAFT.error("Fail to init [BaseRpcServer].");
                    throw new RuntimeException("Fail to init [BaseRpcServer].");
                }
                
                // Initialize multi raft group service framework
                isStarted = true;
                createMultiRaftGroup(processors);
                Loggers.RAFT.info("========= The raft protocol start finished... =========");
            } catch (Exception e) {
                Loggers.RAFT.error("raft protocol start failure, cause: ", e);
                throw new JRaftException(e);
            }
        }
    }
    
    synchronized void createMultiRaftGroup(Collection<RequestProcessor4CP> processors) {
        // There is no reason why the LogProcessor cannot be processed because of the synchronization
        if (!this.isStarted) {
            this.processors.addAll(processors);
            return;

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Check the RAFT logs just above this line (Loggers.RAFT.error) and the JRaftException cause for the bind failure detail.
2. Ensure the raft port (member address) is free: stop stale Nacos/JRaft processes or fix the address.
3. Verify nacos member/cluster.conf or the address server lists the correct, reachable address for this node.
4. Confirm the OS allows binding to the configured port (permissions/firewall).

Example fix

// before: two nodes configured with the same raft address
cluster.conf:
1.1.1.1:7848
1.1.1.1:7848   # duplicate -> init() fails

// after: distinct addresses
cluster.conf:
1.1.1.1:7848
2.2.2.2:7848

// before starting, verify the raft port is free
try (ServerSocket s = new ServerSocket(raftPort)) { /* free */ }
catch (IOException e) { /* port in use — fix config before start */ }

try {
    jRaftServer.start();
} catch (JRaftException e) {
    Throwable c = e.getCause();
    // inspect for BaseRpcServer init failure (port/address)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to install JRaft authentication interceptor
• Illegal Raft system parameters => ReadOnlyOption : [{val}],
• request timeout after {timeout} milliseconds, requestId={req
• Failed to acquire lock: {}
• Failed to unlock: {}

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/4f63e556f96b14bb. Report an issue: GitHub.