apache/incubator-seata · error · FrameworkException

register RM failed. client version: %s,server version: %s, e

Error message

register RM failed. client version: %s,server version: %s, errorMsg: %s, channel: %s

What it means

Thrown from RmNettyRemotingClient.onRegisterMsgFail: the Seata Server returned a failure RegisterRMResponse for the client's resource-manager registration request. The message records client version, server version, the server's errorMsg, and the channel, then wraps everything in a FrameworkException. It means the server actively rejected the RM (not a network failure).

Source

Thrown at core/src/main/java/org/apache/seata/core/rpc/netty/RmNettyRemotingClient.java:241

        getClientChannelManager().registerChannel(serverAddress, channel, registerRMRequest.getVersion());
        getClientChannelManager().putServerVersion(serverAddress, registerRMResponse.getVersion());
        String dbKey = getMergedResourceKeys();
        if (registerRMRequest.getResourceIds() != null) {
            if (!registerRMRequest.getResourceIds().equals(dbKey)) {
                sendRegisterMessage(serverAddress, channel, dbKey);
            }
        }
    }

    @Override
    public void onRegisterMsgFail(
            String serverAddress, Channel channel, Object response, AbstractMessage requestMessage) {
        RegisterRMRequest registerRMRequest = (RegisterRMRequest) requestMessage;
        RegisterRMResponse registerRMResponse = (RegisterRMResponse) response;
        String errMsg = String.format(
                "register RM failed. client version: %s,server version: %s, errorMsg: %s, " + "channel: %s",
                registerRMRequest.getVersion(), registerRMResponse.getVersion(), registerRMResponse.getMsg(), channel);
        throw new FrameworkException(errMsg);
    }

    /**
     * Register new db key.
     *
     * @param resourceGroupId the resource group id
     * @param resourceId      the db key
     */
    public void registerResource(String resourceGroupId, String resourceId) {

        // Resource registration cannot be performed until the RM client is initialized
        if (StringUtils.isBlank(transactionServiceGroup)) {
            return;
        }

        // ResourceId can not be null or empty
        if (StringUtils.isBlank(resourceId)) {
            LOGGER.warn("The resourceId must not be null or empty when registering the RM client.");

View on GitHub (pinned to e01f97c6db)

Solutions

1. Check server log at the same timestamp — the server-side errorMsg included in the message says exactly why it refused (e.g. 'invalid transaction group').
2. Align service.vgroupMapping.<group>=<cluster> in the server config with the client's txServiceGroup so the server recognizes the group.
3. Match client and server versions (upgrade old io.seata clients to org.apache.seata of the same line as the server).
4. Verify the client resolved the right server via registry (registry address, namespace, cluster) and is not hitting a server from another environment.

Example fix

// before: client
RMClient.init(appId, "my_tx_group");  // server has no mapping -> register RM failed

# server application.yml
# (missing)

// after
# server application.yml
seata:
  service:
    vgroupMapping:
      my_tx_group: "default"

// client
RMClient.init(appId, "my_tx_group");  // now registers successfully

// client side: fail fast before RMClient.init if the group has no server mapping
String group = "my_tx_group";
List<String> avail = io.seata.discovery.registry.RegistryFactory.getInstance().lookup(group);
if (avail == null || avail.isEmpty()) {
    throw new IllegalStateException("No seata server found for txServiceGroup " + group + " - fix service.vgroupMapping");
}
RMClient.init(applicationId, group);

try {
    RMClient.init(applicationId, txServiceGroup);
} catch (io.seata.common.exception.FrameworkException e) {
    if (e.getMessage() != null && e.getMessage().contains("register RM failed")) {
        // registration rejected by server: check vgroupMapping/version, do NOT blind-retry
        throw new ConfigurationException("RM registration rejected: " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: Client sends RegisterRMRequest during initResources/registerResource; server replies with a response whose result is not success (e.g. version check rejection, transaction group not hosted by this server, server-side validation failure). The callback onRegisterMsgFail fires and throws FrameworkException.

Common situations: transaction group (txServiceGroup) not present in the server's service.vgroupMapping config, so the server rejects the RM; client/server major version mismatch (e.g. old io.seata client against apache/seata 2.x server); connecting to a server that has not loaded the vgroup mapping; garbled registry data routing the client to the wrong cluster.

Related errors

• can not register RM,err:%s
• register TM failed. client version: %s,server version: %s, e
• register msg is null, role:%s
• register %s error, errMsg:%s
• Invalid event format: expected prefix '{}', got: {}

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