apache/incubator-seata · critical · FrameworkException

can not connect to [{invalidAddress}]

Error message

can not connect to [{invalidAddress}]

What it means

FrameworkException from NettyClientChannelManager: the client had a list of available server addresses and attempted to connect/reconnect to all of them, and every single attempt failed (availList.size() == failedMap.size()). The message enumerates each failing address; the per-address causes were just logged above the throw.

Source

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

                            FrameworkErrorCode.NetConnect.getErrCode(),
                            failedMap.keySet(),
                            failedMap.values().stream()
                                    .map(Throwable::getMessage)
                                    .collect(Collectors.toSet()));
                } else if (LOGGER.isDebugEnabled()) {
                    failedMap.forEach((key, value) -> {
                        LOGGER.error(
                                "{} can not connect to {} cause:{} trace information:",
                                FrameworkErrorCode.NetConnect.getErrCode(),
                                key,
                                value.getMessage(),
                                value);
                    });
                }
            }
            if (availList.size() == failedMap.size()) {
                String invalidAddress = StringUtils.join(failedMap.keySet().iterator(), ", ");
                throw new FrameworkException("can not connect to [" + invalidAddress + "]");
            }
        } finally {
            if (CollectionUtils.isNotEmpty(channelAddress)) {
                List<InetSocketAddress> aliveAddress = new ArrayList<>(channelAddress.size());
                for (String address : channelAddress) {
                    String[] array = NetUtil.splitIPPortStr(address);
                    aliveAddress.add(new InetSocketAddress(array[0], Integer.parseInt(array[1])));
                }
                RegistryFactory.getInstance().refreshAliveLookup(transactionServiceGroup, aliveAddress);
            } else {
                RegistryFactory.getInstance().refreshAliveLookup(transactionServiceGroup, Collections.emptyList());
            }
        }
    }

    void invalidateObject(final String serverAddress, final Channel channel) throws Exception {
        nettyClientKeyPool.invalidateObject(poolKeyMap.get(serverAddress), channel);
    }

View on GitHub (pinned to e01f97c6db)

Solutions

  1. Check the error log lines immediately above the exception: 'can not connect to <addr> cause:...' gives the per-server root cause
  2. Verify each listed address:port is reachable from the client (nc -zv host port)
  3. Fix container port mappings / registry-advertised ports so the listed addresses are the real connect targets
  4. Bring at least one seata-server instance healthy; the client auto-reconnects on the next cycle

Example fix

# docker: before - registry sees host port 8091 but container uses 8091 mapped wrong
SEATA_PORT=8091
# after - ensure the registered port matches the exposed/reachable port
SEATA_PORT=8091  # and publish -p 8091:8091
Defensive patterns

Strategy: retry

Validate before calling

List<String> avail = channelManager.getAvailServerList(txServiceGroup);
if (avail.isEmpty()) { /* wait for registry; skip */ }
// optionally pre-check reachability of each address before reconnect

Try / catch

catch (FrameworkException e) {
    if (e.getMessage().startsWith("can not connect to [")) {
        String addrs = e.getMessage(); // parse failing addresses
        // backoff-retry; page ops if all replicas stay unreachable
    }
}

Prevention

When it happens

Trigger: doReconnect iterating the registry's alive addresses and every connect (getChannel/createChannel) failing: server(s) down, wrong ports, firewall, or registration succeeding at the TCP level but RM registration failing on each.

Common situations: All seata-server replicas unavailable (rolling restart, crashloop); registry returning wrong port (container port vs host port mapping); network policy blocking the whole cluster; servers up but rejecting registration (version/auth incompatibility).

Related errors

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