apache/incubator-seata · error · IllegalArgumentException

"invalid address:" + address

Error message

"invalid address:" + address

What it means

NetUtil.validAddress asserts that an InetSocketAddress is usable for RPC: it must carry a non-null host name and a non-zero port. If either check fails it throws IllegalArgumentException("invalid address:" + address). It is typically invoked when registering or connecting to a Seata server address.

Source

Thrown at common/src/main/java/org/apache/seata/common/util/NetUtil.java:363

            return false;
        }
        for (String regex : ignoredInterfaces) {
            if (interfaceName.matches(regex)) {
                LOGGER.trace("Ignoring interface: {}", interfaceName);
                return true;
            }
        }
        return false;
    }

    /**
     * Valid address.
     *
     * @param address the address
     */
    public static void validAddress(InetSocketAddress address) {
        if (address.getHostName() == null || 0 == address.getPort()) {
            throw new IllegalArgumentException("invalid address:" + address);
        }
    }

    /**
     * is valid address
     *
     * @param address
     * @return true if the given address is valid
     */
    private static boolean isValidAddress(InetAddress address) {
        if (address == null || address.isLoopbackAddress()) {
            return false;
        }
        String hostAddress = address.getHostAddress();
        if (address instanceof Inet6Address) {
            if (!PREFER_IPV6_ADDRESSES) {
                return false;
            }

View on GitHub (pinned to e01f97c6db)

Solutions

1. Ensure the address string includes an explicit port: host:8091
2. Verify the hostname resolves (check DNS/hosts entries, container network) before constructing the address
3. Pass an already-resolved InetSocketAddress created via new InetSocketAddress(InetAddress, port)

Example fix

// before
InetSocketAddress a = NetUtil.toInetSocketAddress("seata-server"); // port defaults to 0
NetUtil.validAddress(a); // throws

// after
InetSocketAddress a = NetUtil.toInetSocketAddress("seata-server:8091");
NetUtil.validAddress(a);

InetSocketAddress a = NetUtil.toInetSocketAddress(host + ":" + port);
if (a.isUnresolved() || a.getPort() == 0) throw new IllegalArgumentException("unusable address: " + a);
NetUtil.validAddress(a);

When it happens

Trigger: Calling validAddress on an address created without resolution — e.g. new InetSocketAddress("unresolved-host", 0), an InetSocketAddress built from a hostname that failed DNS resolution (getHostName() null), or a port of 0 inherited from NetUtil.toInetSocketAddress when the input had no colon (which sets port=0).

Common situations: Passing a hostname-only string through toInetSocketAddress (port defaults to 0), running in an environment where DNS cannot resolve the server host, or a proxy/load-balancer address object constructed with port 0.

Related errors

• %s ,cost: %d ms
• ip and port string cannot be empty!
• "Invalid endpoint format: " + address + ". Endpoint should b
• "Invalid endpoint format: " + address + ". Port must be betw
• "Invalid endpoint format: " + address + ". Port must be a nu

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