apache/incubator-seata · error · IllegalArgumentException

"Invalid endpoint format: " + address + ". Port must be a nu

Error message

"Invalid endpoint format: " + address + ". Port must be a numeric value."

What it means

NetUtil.splitIPPortStr requires the port substring after the last colon to be a pure integer. When Integer.parseInt(portStr) throws NumberFormatException, it is rethrown as IllegalArgumentException("Invalid endpoint format ... Port must be a numeric value") with the original cause attached.

Source

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

        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.");
        }
    }

    /**
     * To long long.
     *
     * @param address the address
     * @return the long
     */
    public static long toLong(String address) {
        InetSocketAddress ad = toInetSocketAddress(address);

View on GitHub (pinned to e01f97c6db)

Solutions

1. Pass only host:port — strip any scheme such as http:// before parsing
2. Bracket IPv6 addresses: [fe80::1]:8091
3. Trim whitespace and remove non-digit characters from the port segment

Example fix

// before
NetUtil.splitIPPortStr("http://127.0.0.1:8091");

// after
String a = "http://127.0.0.1:8091".replaceFirst("^https?://", "");
NetUtil.splitIPPortStr(a);

String[] parts = address.split(":");
if (!parts[parts.length - 1].matches("\\d+")) throw new IllegalArgumentException("port not numeric: " + address);

When it happens

Trigger: Calling splitIPPortStr/toInetSocketAddress with a non-numeric port: "host:http", "host:80 91", or an unbracketed IPv6 literal like "fe80::1:8091" where the last colon splits inside the address and the tail is not a plain number. Also URLs including a scheme ("http://host:8091") mis-split so the port part becomes "//host:8091"-derived garbage.

Common situations: Passing full URLs instead of host:port, unbracketed IPv6 addresses, trailing whitespace or units in the port ("8091 "), and YAML unquoted values where ': ' parsing corrupts the string.

Related errors

• "Invalid endpoint format: " + address + ". Endpoint should b
• "Invalid endpoint format: " + address + ". Port must be betw
• ip and port string cannot be empty!
• "invalid address:" + address
• Watch request failed: {}

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