apache/incubator-seata · error · IllegalArgumentException

"Invalid endpoint format: " + address + ". Port must be betw

Error message

"Invalid endpoint format: " + address + ". Port must be between 1 and 65535."

What it means

NetUtil.splitIPPortStr validates the port segment after parsing it as an integer; a port must be between 1 and 65535. This IllegalArgumentException is thrown when the numeric port is out of range — 0, negative, or above 65535 — so the address can never produce a usable socket.

Source

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

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

    /**
     * To long long.
     *
     * @param address the address

View on GitHub (pinned to e01f97c6db)

Solutions

1. Set the port to a valid TCP port in [1, 65535] (Seata default is 8091 for the server, 8080/8091 common for console)
2. Check the specific property (server.port, grouplist address) for 0 or 5-digit typos
3. Validate ports at deployment time (e.g. JSON schema or Helm values check)

Example fix

# before
service.default.grouplist = 127.0.0.1:0

# after
service.default.grouplist = 127.0.0.1:8091

String[] p = address.split(":");
int port = Integer.parseInt(p[p.length - 1]);
if (port < 1 || port > 65535) throw new IllegalArgumentException("port out of range: " + address);

When it happens

Trigger: Calling splitIPPortStr/toInetSocketAddress with addresses like "127.0.0.1:0", "host:70000", or "host:-1". The port parses as a number but fails the 1..65535 bounds check.

Common situations: Misconfigured port in seata server/grouplist properties (e.g. port set to 0 meaning 'unset' by a deployment tool), copy-paste errors appending an extra digit, or environment-variable port defaults of 0.

Related errors

• ip and port string cannot be empty!
• "Invalid endpoint format: " + address + ". Endpoint should b
• "Invalid endpoint format: " + address + ". Port must be a nu
• listen port: %s is invalid!
• ERR_CONFIG

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