apache/incubator-seata · error · FrameworkException

register %s error, errMsg:%s

Error message

register %s error, errMsg:%s

What it means

FrameworkException from NettyPoolableFactory.makeObject: the channel was created and the register request sent, but sending/processing it threw (sendSyncRequest failure or the register-fail callback itself), so the temp channel is closed and this exception wraps the original cause's message. Role in the message (TM/RM) tells you which register failed.

Source

Thrown at core/src/main/java/org/apache/seata/core/rpc/netty/NettyPoolableFactory.java:78

        Object response;
        Channel channelToServer = null;
        if (key.getMessage() == null) {
            throw new FrameworkException(
                    "register msg is null, role:" + key.getTransactionRole().name());
        }
        try {
            response = rpcRemotingClient.sendSyncRequest(tmpChannel, key.getMessage());
            if (!isRegisterSuccess(response, key.getTransactionRole())) {
                rpcRemotingClient.onRegisterMsgFail(key.getAddress(), tmpChannel, response, key.getMessage());
            } else {
                channelToServer = tmpChannel;
                rpcRemotingClient.onRegisterMsgSuccess(key.getAddress(), tmpChannel, response, key.getMessage());
            }
        } catch (Exception exx) {
            if (tmpChannel != null) {
                tmpChannel.close();
            }
            throw new FrameworkException(
                    "register " + key.getTransactionRole().name() + " error, errMsg:" + exx.getMessage());
        }
        if (LOGGER.isInfoEnabled()) {
            LOGGER.info("register success, cost " + (System.currentTimeMillis() - start) + " ms, version:"
                    + getVersion(response, key.getTransactionRole()) + ",role:"
                    + key.getTransactionRole().name() + ",channel:"
                    + channelToServer);
        }
        return channelToServer;
    }

    private boolean isRegisterSuccess(Object response, NettyPoolKey.TransactionRole transactionRole) {
        if (response == null) {
            return false;
        }
        if (transactionRole.equals(NettyPoolKey.TransactionRole.TMROLE)) {
            if (!(response instanceof RegisterTMResponse)) {
                return false;

View on GitHub (pinned to e01f97c6db)

Solutions

1. Read the nested errMsg: timeouts -> raise rpc request timeout; rejected -> fix auth/credentials; reset -> check server logs for the close reason
2. Align username/password between seata-server security config and the client
3. Align client and server versions so the register response parses and validates
4. Delay client traffic until the server is fully up, or rely on the client's background reconnect

Example fix

# before: server requires auth, client sends none
# client application.yml — add:
seata:
  client:
    tm: { username: seata, password: seata }
    rm: { username: seata, password: seata }

// ensure credentials present before first borrow
if (serverAuthEnabled && clientUsername == null) {
    throw new IllegalStateException("seata server auth is on; set client username/password");
}

catch (FrameworkException e) {
    if (e.getMessage().startsWith("register TM") || e.getMessage().startsWith("register RM")) {
        String cause = e.getMessage(); // errMsg suffix carries root cause
        // fix auth/version/timeout per cause; reconnect retries registration
    }
}

When it happens

Trigger: During pool object creation: rpcRemotingClient.sendSyncRequest(tmpChannel, registerRequest) throws (timeout, connection reset), or isRegisterSuccess is false and onRegisterMsgFail throws (server rejected registration).

Common situations: Server rejects registration (auth enabled without matching client credentials, version-incompatible register response); connect succeeded at TCP level but server closed the connection mid-handshake; high load making the sync register exceed rpcRequestTimeout; server still initializing when client registers.

Related errors

• connect failed, can not connect to services-server.
• can not register RM,err:%s
• register msg is null, role:%s
• register RM failed. client version: %s,server version: %s, e
• register TM failed. client version: %s,server version: %s, e

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