apache/incubator-seata · critical · RuntimeException

Server start failed

Error message

Server start failed

What it means

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.

Solutions

  1. Read the chained cause exception (exx) in the stack trace — it names the actual failing component (usually a specific RegistryService).
  2. Verify registry connectivity from the server host: registry address, port, namespace, username/password (e.g. `curl http://<nacos>:8848/nacos`).
  3. Fix registry.* keys in registry.conf / application.yml to match your registry cluster and restart.
  4. If you do not want external registration, set registry.type=file to rule the registry out and retest startup.
  5. Check XID network config (XID.getIpAddress/getPort) if the cause points at endpoint setup on multi-NIC hosts.

Example fix

# before (registry.conf)
registry {
  type = "nacos"
  nacos {
    serverAddr = "nacos:8848"   # wrong/unreachable -> Server start failed
  }
}

# after
registry {
  type = "nacos"
  nacos {
    serverAddr = "10.0.0.5:8848"
    namespace = ""
    username = "nacos"
    password = "nacos"
  }
}
Defensive patterns

Strategy: try-catch

Validate before calling

// verify registry reachability before starting the server (nacos example)
// curl-equivalent in Java omitted; simplest: preflight with the registry client
// Nacos: check /nacos/v1/console/health/liveness returns 200 before bootstrap

Try / catch

try {
    server.start();
} catch (RuntimeException e) {
    Throwable cause = e.getCause() != null ? e.getCause() : e;
    log.error("seata server start failed, root cause: {}", cause.toString());
    // distinguish registry failure vs bind failure from the cause chain before retrying
    throw e;
}

Prevention

When it happens

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

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

Related errors

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/057a74e4cec2042c. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/seata/core/rpc/netty/NettyServerBootstrap.java:209

                    }
                });

        try {
            this.serverBootstrap.bind(port).sync();
            LOGGER.info("Server started, service listen port: {}", getListenPort());
            Instance instance = Instance.getInstance();
            // Lines 177-180 are just for compatibility with test cases
            if (instance.getTransaction() == null) {
                Instance.getInstance().setTransaction(new Node.Endpoint(XID.getIpAddress(), XID.getPort(), "netty"));
            }
            for (RegistryService<?> registryService : MultiRegistryFactory.getInstances()) {
                registryService.register(Instance.getInstance());
            }
            initialized.set(true);
        } catch (SocketException se) {
            throw new RuntimeException("Server start failed, the listen port: " + getListenPort(), se);
        } catch (Exception exx) {
            throw new RuntimeException("Server start failed", exx);
        }
    }

    @Override
    public void shutdown() {
        try {
            if (LOGGER.isInfoEnabled()) {
                LOGGER.info("Shutting server down, the listen port: {}", getListenPort());
            }
            if (initialized.get()) {
                for (RegistryService registryService : MultiRegistryFactory.getInstances()) {
                    registryService.unregister(Instance.getInstance());
                    registryService.close();
                }
                // wait a few seconds for server transport
                TimeUnit.SECONDS.sleep(nettyServerConfig.getServerShutdownWaitTime());
            }

View on GitHub (pinned to e01f97c6db)