apache/incubator-seata · error · ParseEndpointException

Invalid format for endpoint: {}

Error message

Invalid format for endpoint: {}

What it means

Same parser (Node.createExternalEndpoints): when an entry split on ':' does not yield exactly 3 parts (host, controllerPort, transactionPort), it throws ParseEndpointException 'Invalid format for endpoint: <entry>'. This is the shape error as opposed to the numeric port error.

Source

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

    }

    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;
        }
        if (obj instanceof List) {
            List<Node.ExternalEndpoint> oldList = (List<Node.ExternalEndpoint>) obj;

View on GitHub (pinned to e01f97c6db)

Solutions

1. Rewrite each comma-separated entry as host:controllerPort:transactionPort.
2. Remove trailing/duplicate commas from the property.
3. Do not put the console-only address or a bare host into this property; both ports are mandatory.
4. For IPv6, use a DNS hostname since the parser cannot disambiguate colons.

Example fix

# before
external.endpoints=seata.example.com:7091,seata2.example.com:7091:8091

# after
external.endpoints=seata.example.com:7091:8091,seata2.example.com:7091:8091

// Enforce the 3-part host:ctrlPort:txPort shape before parsing
boolean validShape(String entry) {
    String[] parts = entry.split(":");
    return parts.length == 3 && !parts[0].isEmpty() && !parts[1].isEmpty() && !parts[2].isEmpty();
}

try {
    node.createExternalEndpoints(external);
} catch (ParseEndpointException e) {
    if (e.getMessage().startsWith("Invalid format")) {
        // entry had wrong number of colon-separated parts; show expected host:ctrl:tx format
    }
    throw e;
}

When it happens

Trigger: server external endpoint string contains 'host:8091' (missing transaction port), 'host' (no ports), 'host:7091:8091:extra', or an empty segment between commas such as 'a.io:1:2,'.

Common situations: Copy-pasting only part of an endpoint into server.external-endpoints; using a single-port address like the console-only 'host:7091'; trailing commas after the last entry; IPv6 literals producing more than 3 colon-separated parts.

Related errors

• Invalid port number in: {}
• "\"" + 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/1fb5973a413e1b8a. Report an issue: GitHub.