What causes "Failed to get available servers" in apache/incubator-seata?

Verify the registry (e.g. Nacos) is reachable from the application and credentials/namespace/group are correct

apache/incubator-seata · error · FrameworkException

Failed to get available servers

Error message

Failed to get available servers

What it means

Error path in NettyClientChannelManager.doReconnect: querying the registry for the transaction service group's server list threw (RegistryFactory.getInstance().lookup failed). The lookup exception is logged; then, if failFast is enabled, a fail-fast exception with this message is thrown, otherwise the method returns and the reconnect is skipped this cycle.

Source

Thrown at core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientChannelManager.java:201

     * @param transactionServiceGroup
     * @param failFast
     */
    void initReconnect(String transactionServiceGroup, boolean failFast) {
        doReconnect(transactionServiceGroup, failFast);
    }

    /**
     * reconnect to remote server of current transaction service group.
     * @param transactionServiceGroup
     * @param failFast
     */
    void doReconnect(String transactionServiceGroup, boolean failFast) {
        List<String> availList;
        try {
            availList = getAvailServerList(transactionServiceGroup);
        } catch (Exception e) {
            LOGGER.error("Failed to get available servers: {}", e.getMessage(), e);
            throwFailFastException(failFast, "Failed to get available servers");
            return;
        }
        if (CollectionUtils.isEmpty(availList)) {
            RegistryService registryService = RegistryFactory.getInstance();
            String clusterName = registryService.getServiceGroup(transactionServiceGroup);

            if (StringUtils.isBlank(clusterName)) {
                LOGGER.error(
                        "can not get cluster name in registry config '{}{}', please make sure registry config correct",
                        ConfigurationKeys.SERVICE_GROUP_MAPPING_PREFIX,
                        transactionServiceGroup);
                throwFailFastException(failFast, "can not get cluster name in registry config.");
                return;
            }

            if (!(registryService instanceof FileRegistryServiceImpl)) {
                LOGGER.error(
                        "no available service found in cluster '{}', please make sure registry config correct and keep your seata server running",

View on GitHub (pinned to e01f97c6db)

Solutions

Verify the registry (e.g. Nacos) is reachable from the application and credentials/namespace/group are correct
Compare the client's registry type and address config with the seata-server's registry config
If the registry may be temporarily unavailable at boot, disable fail-fast so the client retries in the background instead of aborting startup
Re-run the startup and check the logged lookup exception for the exact registry error

Example fix

# application.yml
seata:
  client:
    rm:
      fail-fast: false   # was true; registry briefly unavailable at boot
# fix registry address instead if it is wrong:
#   registry: type: nacos, nacos: server-addr: correct-host:8848

Defensive patterns

Strategy: try-catch

Validate before calling

// startup guard: try a registry lookup before enabling fail-fast
List<InetSocketAddress> list = RegistryFactory.getInstance().lookup(txServiceGroup); // throws early if registry is down

Try / catch

catch (Exception e) {
    if (e.getMessage().equals("Failed to get available servers")) {
        // registry outage: either fail startup deliberately or disable fail-fast and retry
    }
}

Prevention

Only enable fail-fast when the registry is guaranteed available at boot
Add retry/health checks for the registry in the app's init phase
Lock registry config (type/address/namespace) in config review

When it happens

Trigger: failFast=true (e.g. application startup with seata.client.rm.fail-fast / enable-fail-fast) plus a registry error: Nacos/etcd/Redis/ZooKeeper connection failure, timeout, auth error, or missing namespace/group during lookup of the service group.

Common situations: Registry cluster unreachable from the app at startup; wrong registry address/namespace/group in registry.conf or application.yml; registry credentials missing; slow registry causing lookup timeouts during boot.

Related errors

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