apache/incubator-seata · error · ParseEndpointException

Invalid port number in: {}

Error message

Invalid port number in: {}

What it means

Node.createExternalEndpoints parses the server's 'external' endpoint setting, a comma-separated list of host:controllerPort:transactionPort entries. Integer.parseInt on either port throws NumberFormatException and is rethrown as ParseEndpointException 'Invalid port number in: <entry>' naming the exact malformed entry.

Source

Thrown at common/src/main/java/org/apache/seata/common/metadata/Node.java:217

    private Node.ExternalEndpoint createExternalEndpoint(String host, int controllerPort, int transactionPort) {
        return new Node.ExternalEndpoint(host, controllerPort, transactionPort);
    }

    public List<ExternalEndpoint> createExternalEndpoints(String external) {
        List<Node.ExternalEndpoint> externalEndpoints = new ArrayList<>();
        String[] split = external.split(",");

        for (String s : split) {
            String[] item = s.split(":");
            if (item.length == 3) {
                try {
                    String host = item[0];
                    int controllerPort = Integer.parseInt(item[1]);
                    int transactionPort = Integer.parseInt(item[2]);
                    externalEndpoints.add(createExternalEndpoint(host, controllerPort, transactionPort));
                } catch (NumberFormatException e) {
                    throw new ParseEndpointException("Invalid port number in: " + s);
                }
            } else {
                throw new ParseEndpointException("Invalid format for endpoint: " + s);
            }
        }
        return externalEndpoints;
    }

    public Map<String, Object> updateMetadataWithExternalEndpoints(
            Map<String, Object> metadata, List<Node.ExternalEndpoint> externalEndpoints) {
        Object obj = metadata.get("external");
        if (obj == null) {
            if (!externalEndpoints.isEmpty()) {
                Map<String, Object> metadataMap = new HashMap<>(metadata);
                metadataMap.put("external", externalEndpoints);
                return metadataMap;
            }
            return metadata;

View on GitHub (pinned to e01f97c6db)

Solutions

1. Correct the reported entry to exactly host:numericControllerPort:numericTransactionPort.
2. Remove stray characters/spaces/units from port fields.
3. For IPv6 hosts, use the hostname or wrap per your seata version's supported syntax — the naive split(":") only supports 3 colon-separated parts.
4. Validate the whole property with a regex before restart (see defense).

Example fix

# before
external.endpoints=e1.seata.io:7091:8O91   # letter O instead of zero

# after
external.endpoints=e1.seata.io:7091:8091

// Validate external endpoints config before server bootstrap
private static final Pattern ENDPOINT = Pattern.compile("^[^,:]+:\\d{1,5}:\\d{1,5}$");
void validateExternalEndpoints(String external) {
    for (String s : external.split(",", -1)) {
        if (!ENDPOINT.matcher(s.trim()).matches())
            throw new IllegalArgumentException("Bad external endpoint entry: " + s);
    }
}

try {
    List<Node.ExternalEndpoint> eps = node.createExternalEndpoints(external);
} catch (ParseEndpointException e) {
    // message contains the exact malformed entry; reject config with a clear startup error
    throw new IllegalArgumentException("server.external-endpoints misconfigured: " + e.getMessage(), e);
}

When it happens

Trigger: Calling createExternalEndpoints(external) (directly or via server bootstrap reading server.external-endpoints) with a value like 'e1.seata.io:7091:8091,e2.seata.io:abc:8091' where a port field is non-numeric, or values like 'host:8091:8091.5' or 'host:80 91:8092'.

Common situations: Typos in server.external-endpoints config; trailing units ('8091s'), spaces, empty port fields ('host::8091'), or IPv6 addresses whose colons break the 3-part split expectation.

Related errors

• Invalid format for endpoint: {}
• "\"" + str + "\" can't parse to Duration"
• Watch request failed with code %d: %s
• Unknown StateType[{value}]
• not found service provider for : {}

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