{"record":{"id":"44d22f580ce1c8fd","repo":"apache/incubator-seata","slug":"can-not-get-cluster-name-in-registry-config","errorCode":null,"errorMessage":"can not get cluster name in registry config.","messagePattern":"can not get cluster name in registry config\\.","errorType":"exception","errorClass":"FrameworkException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientChannelManager.java","lineNumber":213,"sourceCode":"    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\",\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);","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientChannelManager.java#L195-L231","documentation":"Error path in NettyClientChannelManager.doReconnect: the registry lookup succeeded but returned no instances, and mapping the transaction service group to a cluster name via registryService.getServiceGroup returned blank. Seata resolves vgroupMapping.<group>=<cluster> through configuration; if that key is absent (or blank), the client cannot even know which cluster to search, and this fail-fast message reports it.","triggerScenarios":"failFast=true with a transaction service group that has no service.vgroupMapping.<group> entry in the client's configuration (file, Nacos config center, etc.).","commonSituations":"Missing or typo'd service.vgroupMapping key in application.yml/registry.conf; config not loaded from the config center (wrong config type/namespace/dataId); upgrading config format (registry.conf -> application.yml) and dropping the mapping; group name mismatch between @GlobalTransactional usage and the mapping key.","solutions":["Add/correct the mapping: service.vgroupMapping.<your-tx-group>=<cluster> (older key: serviceGroupMapping / grouplist) in the client's config source","If using a config center, confirm the client actually reads that dataId (check config type, group, namespace)","Ensure the seata-server has the inverse mapping service.group.<cluster>=<tx-group> or at least registers into <cluster>","Verify the group name used by the app matches the mapping key exactly (case-sensitive)"],"exampleFix":"# application.yml — before: no mapping\nseata:\n  tx-service-group: my_tx_group   # nothing maps it\n\n# after\nseata:\n  tx-service-group: my_tx_group\n  service:\n    vgroup-mapping:\n      my_tx_group: default","handlingStrategy":"validation","validationCode":"String cluster = ConfigurationFactory.getInstance()\n    .getConfig(\"service.vgroupMapping.\" + txServiceGroup);\nif (StringUtils.isBlank(cluster)) {\n    throw new IllegalStateException(\"missing vgroupMapping for \" + txServiceGroup);\n}","typeGuard":"boolean hasVgroupMapping(String group) {\n    return StringUtils.isNotBlank(\n        ConfigurationFactory.getInstance().getConfig(\"service.vgroupMapping.\" + group));\n}","tryCatchPattern":"catch (Exception e) {\n    if (\"can not get cluster name in registry config.\".equals(e.getMessage())) {\n        // add service.vgroupMapping.<group>=<cluster> and restart\n    }\n}","preventionTips":["Declare vgroupMapping in the same config source the client actually loads","Add a config startup assertion for the tx-service-group mapping key","Test config after migrating registry.conf -> application.yml"],"tags":["config","vgroup-mapping","startup","client"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}