apache/incubator-seata · critical · FrameworkException

can not get cluster name in registry config.

Error message

can not get cluster name in registry config.

What it means

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.

Source

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

    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",
                        clusterName);
            }
            throwFailFastException(failFast, "no available service found in cluster.");
            return;
        }
        try {
            doReconnect(availList, transactionServiceGroup);
        } catch (Exception e) {
            if (failFast) {
                throw e;
            }
            LOGGER.error("connect server failed. {}", e.getMessage(), e);

View on GitHub (pinned to e01f97c6db)

Solutions

1. Add/correct the mapping: service.vgroupMapping.<your-tx-group>=<cluster> (older key: serviceGroupMapping / grouplist) in the client's config source
2. If using a config center, confirm the client actually reads that dataId (check config type, group, namespace)
3. Ensure the seata-server has the inverse mapping service.group.<cluster>=<tx-group> or at least registers into <cluster>
4. Verify the group name used by the app matches the mapping key exactly (case-sensitive)

Example fix

# application.yml — before: no mapping
seata:
  tx-service-group: my_tx_group   # nothing maps it

# after
seata:
  tx-service-group: my_tx_group
  service:
    vgroup-mapping:
      my_tx_group: default

String cluster = ConfigurationFactory.getInstance()
    .getConfig("service.vgroupMapping." + txServiceGroup);
if (StringUtils.isBlank(cluster)) {
    throw new IllegalStateException("missing vgroupMapping for " + txServiceGroup);
}

boolean hasVgroupMapping(String group) {
    return StringUtils.isNotBlank(
        ConfigurationFactory.getInstance().getConfig("service.vgroupMapping." + group));
}

catch (Exception e) {
    if ("can not get cluster name in registry config.".equals(e.getMessage())) {
        // add service.vgroupMapping.<group>=<cluster> and restart
    }
}

When it happens

Trigger: failFast=true with a transaction service group that has no service.vgroupMapping.<group> entry in the client's configuration (file, Nacos config center, etc.).

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

Related errors

• ERR_CONFIG
• Apollo configuration initialized failed,please check the val
• config type can not be null
• file not found
• not support config data type type: %s

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