apache/incubator-seata · error · IllegalArgumentException

"Invalid endpoint format: " + address + ". Endpoint should b

Error message

"Invalid endpoint format: " + address + ". Endpoint should be in the format ip:port."

What it means

After splitting an address on the last ':' (colon), NetUtil.splitIPPortStr requires both a non-blank host part and a non-blank port part. This IllegalArgumentException ("Invalid endpoint format ... Endpoint should be in the format ip:port") fires when one side is empty: an address like ":8091" (no host) or "localhost:" (no port).

Source

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

        return new InetSocketAddress(host, port);
    }

    public static String[] splitIPPortStr(String address) {
        if (StringUtils.isBlank(address)) {
            throw new IllegalArgumentException("ip and port string cannot be empty!");
        }
        if (address.charAt(0) == '[') {
            address = removeBrackets(address);
        }
        int i = address.lastIndexOf(Constants.IP_PORT_SPLIT_CHAR);
        if (i > -1) {
            String hostAddress = address.substring(0, i);
            if (hostAddress.contains("%")) {
                hostAddress = hostAddress.substring(0, hostAddress.indexOf("%"));
            }
            String portStr = address.substring(i + 1);
            if (StringUtils.isBlank(hostAddress) || StringUtils.isBlank(portStr)) {
                throw new IllegalArgumentException(
                        "Invalid endpoint format: " + address + ". Endpoint should be in the format ip:port.");
            }
            try {
                int port = Integer.parseInt(portStr);
                if (port < 1 || port > 65535) {
                    throw new IllegalArgumentException(
                            "Invalid endpoint format: " + address + ". Port must be between 1 and 65535.");
                }
            } catch (NumberFormatException e) {
                throw new IllegalArgumentException(
                        "Invalid endpoint format: " + address + ". Port must be a numeric value.", e);
            }

            return new String[] {hostAddress, portStr};
        } else {
            throw new IllegalArgumentException(
                    "Invalid endpoint format: " + address + ". Endpoint should be in the format ip:port.");
        }

View on GitHub (pinned to e01f97c6db)

Solutions

1. Fix the address to a full ip:port (or [ipv6]:port) form
2. Wrap IPv6 literals in square brackets: [::1]:8091
3. Quote/escape YAML values so colons are not mangled; ensure template variables resolve

Example fix

# before (config)
address = ":8091"

# after
address = "127.0.0.1:8091"

private static final Pattern EP = Pattern.compile("^\\[?[\\w.%:]+\\]?:\\d+$");
if (!EP.matcher(address).matches()) throw new IllegalArgumentException("bad endpoint: " + address);

try { parts = NetUtil.splitIPPortStr(a); } catch (IllegalArgumentException e) { log.warn("skipping malformed endpoint {}", a); }

When it happens

Trigger: Calling splitIPPortStr / toInetSocketAddress with strings such as ":8091", "host:", or where the only colon produced an empty segment. IPv6 addresses without brackets (e.g. "::1:8091") can also mis-split because lastIndexOf(':') finds a colon inside the address, yielding a garbage host and non-numeric or blank port.

Common situations: Manually edited registry addresses with a typo, templated config that substitutes an empty host variable ("${HOST}:8091" with HOST unset), or unbracketed IPv6 literals.

Related errors

• ip and port string cannot be empty!
• "Invalid endpoint format: " + address + ". Port must be betw
• "Invalid endpoint format: " + address + ". Port must be a nu
• ERR_CONFIG
• URL must not be null or blank

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