{"record":{"id":"56469485c7d78693","repo":"apache/incubator-seata","slug":"failed-to-get-available-servers","errorCode":null,"errorMessage":"Failed to get available servers","messagePattern":"Failed to get available servers","errorType":"exception","errorClass":"FrameworkException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientChannelManager.java","lineNumber":201,"sourceCode":"     * @param transactionServiceGroup\n     * @param failFast\n     */\n    void initReconnect(String transactionServiceGroup, boolean failFast) {\n        doReconnect(transactionServiceGroup, failFast);\n    }\n\n    /**\n     * reconnect to remote server of current transaction service group.\n     * @param transactionServiceGroup\n     * @param failFast\n     */\n    void doReconnect(String transactionServiceGroup, boolean failFast) {\n        List<String> availList;\n        try {\n            availList = getAvailServerList(transactionServiceGroup);\n        } catch (Exception e) {\n            LOGGER.error(\"Failed to get available servers: {}\", e.getMessage(), e);\n            throwFailFastException(failFast, \"Failed to get available servers\");\n            return;\n        }\n        if (CollectionUtils.isEmpty(availList)) {\n            RegistryService registryService = RegistryFactory.getInstance();\n            String clusterName = registryService.getServiceGroup(transactionServiceGroup);\n\n            if (StringUtils.isBlank(clusterName)) {\n                LOGGER.error(\n                        \"can not get cluster name in registry config '{}{}', please make sure registry config correct\",\n                        ConfigurationKeys.SERVICE_GROUP_MAPPING_PREFIX,\n                        transactionServiceGroup);\n                throwFailFastException(failFast, \"can not get cluster name in registry config.\");\n                return;\n            }\n\n            if (!(registryService instanceof FileRegistryServiceImpl)) {\n                LOGGER.error(\n                        \"no available service found in cluster '{}', please make sure registry config correct and keep your seata server running\",","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientChannelManager.java#L183-L219","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# application.yml\nseata:\n  client:\n    rm:\n      fail-fast: false   # was true; registry briefly unavailable at boot\n# fix registry address instead if it is wrong:\n#   registry: type: nacos, nacos: server-addr: correct-host:8848","handlingStrategy":"try-catch","validationCode":"// startup guard: try a registry lookup before enabling fail-fast\nList<InetSocketAddress> list = RegistryFactory.getInstance().lookup(txServiceGroup); // throws early if registry is down","typeGuard":null,"tryCatchPattern":"catch (Exception e) {\n    if (e.getMessage().equals(\"Failed to get available servers\")) {\n        // registry outage: either fail startup deliberately or disable fail-fast and retry\n    }\n}","preventionTips":["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"],"tags":["registry","fail-fast","startup","client"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}