{"record":{"id":"45781869056a0a7b","repo":"apache/incubator-seata","slug":"no-available-service-found-in-cluster","errorCode":null,"errorMessage":"no available service found in cluster.","messagePattern":"no available service found in cluster\\.","errorType":"exception","errorClass":"FrameworkException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientChannelManager.java","lineNumber":222,"sourceCode":"        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\",\n                        clusterName);\n            }\n            throwFailFastException(failFast, \"no available service found in cluster.\");\n            return;\n        }\n        try {\n            doReconnect(availList, transactionServiceGroup);\n        } catch (Exception e) {\n            if (failFast) {\n                throw e;\n            }\n            LOGGER.error(\"connect server failed. {}\", e.getMessage(), e);\n        }\n    }\n\n    /**\n     * Reconnect to remote server of current transaction service group.\n     *\n     * @param availList avail list\n     * @param transactionServiceGroup transaction service group\n     */","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientChannelManager.java#L204-L240","documentation":"Error path in NettyClientChannelManager.doReconnect: the vgroup->cluster mapping resolved fine, but the registry lookup for that cluster returned zero instances (and the registry is not the File-based fallback). The client knows which cluster to search yet finds no live seata-server registered there; with failFast this message is thrown, otherwise it is only logged and retried.","triggerScenarios":"failFast=true with a correct cluster mapping but an empty instance list in the registry: no seata-server registered, instances failed health checks, or registered under a different cluster name/group/namespace.","commonSituations":"seata-server not started; server registered to a different cluster name (service.default.grouplist vs registry cluster); Nacos namespace/group mismatch between server registration and client lookup; all instances pruned after network issues.","solutions":["Start the seata-server and confirm it registers (check the registry console for instances in the expected cluster/namespace/group)","Make the cluster name in the client's vgroupMapping match the cluster the server registers to (seata.server.cluster / registry config)","Align namespace and group between server registration and client lookup in the registry","If servers are healthy but temporarily absent, disable fail-fast to let the client keep retrying in the background"],"exampleFix":"# server application.yml\nseata:\n  registry:\n    type: nacos\n    nacos:\n      cluster: default     # must equal the value in the client's vgroup-mapping\n# client application.yml\nseata:\n  service:\n    vgroup-mapping:\n      my_tx_group: default # <- matches 'default'","handlingStrategy":"validation","validationCode":"List<InetSocketAddress> instances = RegistryFactory.getInstance().lookup(txServiceGroup);\nif (CollectionUtils.isEmpty(instances)) {\n    // cluster empty: block startup or fall back to file grouplist\n}","typeGuard":null,"tryCatchPattern":"catch (Exception e) {\n    if (\"no available service found in cluster.\".equals(e.getMessage())) {\n        // check server registration in registry console; retry once servers appear\n    }\n}","preventionTips":["Run health checks on seata-server registration, not just process liveness","Match cluster/namespace/group between server and client registry configs","Keep fail-fast off in environments where servers start after clients"],"tags":["registry","no-instances","startup","client"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}