apache/incubator-seata · critical · FrameworkException

no available service found in cluster.

Error message

no available service found in cluster.

What it means

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.

Source

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

        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);
        }
    }

    /**
     * Reconnect to remote server of current transaction service group.
     *
     * @param availList avail list
     * @param transactionServiceGroup transaction service group
     */

View on GitHub (pinned to e01f97c6db)

Solutions

  1. Start the seata-server and confirm it registers (check the registry console for instances in the expected cluster/namespace/group)
  2. Make the cluster name in the client's vgroupMapping match the cluster the server registers to (seata.server.cluster / registry config)
  3. Align namespace and group between server registration and client lookup in the registry
  4. If servers are healthy but temporarily absent, disable fail-fast to let the client keep retrying in the background

Example fix

# server application.yml
seata:
  registry:
    type: nacos
    nacos:
      cluster: default     # must equal the value in the client's vgroup-mapping
# client application.yml
seata:
  service:
    vgroup-mapping:
      my_tx_group: default # <- matches 'default'
Defensive patterns

Strategy: validation

Validate before calling

List<InetSocketAddress> instances = RegistryFactory.getInstance().lookup(txServiceGroup);
if (CollectionUtils.isEmpty(instances)) {
    // cluster empty: block startup or fall back to file grouplist
}

Try / catch

catch (Exception e) {
    if ("no available service found in cluster.".equals(e.getMessage())) {
        // check server registration in registry console; retry once servers appear
    }
}

Prevention

When it happens

Trigger: 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.

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

Related errors

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