{"record":{"id":"1fb5973a413e1b8a","repo":"apache/incubator-seata","slug":"invalid-format-for-endpoint","errorCode":null,"errorMessage":"Invalid format for endpoint: {}","messagePattern":"Invalid format for endpoint: (.+?)","errorType":"validation","errorClass":"ParseEndpointException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/org/apache/seata/common/metadata/Node.java","lineNumber":220,"sourceCode":"    }\n\n    public List<ExternalEndpoint> createExternalEndpoints(String external) {\n        List<Node.ExternalEndpoint> externalEndpoints = new ArrayList<>();\n        String[] split = external.split(\",\");\n\n        for (String s : split) {\n            String[] item = s.split(\":\");\n            if (item.length == 3) {\n                try {\n                    String host = item[0];\n                    int controllerPort = Integer.parseInt(item[1]);\n                    int transactionPort = Integer.parseInt(item[2]);\n                    externalEndpoints.add(createExternalEndpoint(host, controllerPort, transactionPort));\n                } catch (NumberFormatException e) {\n                    throw new ParseEndpointException(\"Invalid port number in: \" + s);\n                }\n            } else {\n                throw new ParseEndpointException(\"Invalid format for endpoint: \" + s);\n            }\n        }\n        return externalEndpoints;\n    }\n\n    public Map<String, Object> updateMetadataWithExternalEndpoints(\n            Map<String, Object> metadata, List<Node.ExternalEndpoint> externalEndpoints) {\n        Object obj = metadata.get(\"external\");\n        if (obj == null) {\n            if (!externalEndpoints.isEmpty()) {\n                Map<String, Object> metadataMap = new HashMap<>(metadata);\n                metadataMap.put(\"external\", externalEndpoints);\n                return metadataMap;\n            }\n            return metadata;\n        }\n        if (obj instanceof List) {\n            List<Node.ExternalEndpoint> oldList = (List<Node.ExternalEndpoint>) obj;","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/common/src/main/java/org/apache/seata/common/metadata/Node.java#L202-L238","documentation":"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.","triggerScenarios":"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,'.","commonSituations":"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.","solutions":["Rewrite each comma-separated entry as host:controllerPort:transactionPort.","Remove trailing/duplicate commas from the property.","Do not put the console-only address or a bare host into this property; both ports are mandatory.","For IPv6, use a DNS hostname since the parser cannot disambiguate colons."],"exampleFix":"# before\nexternal.endpoints=seata.example.com:7091,seata2.example.com:7091:8091\n\n# after\nexternal.endpoints=seata.example.com:7091:8091,seata2.example.com:7091:8091","handlingStrategy":"validation","validationCode":"// Enforce the 3-part host:ctrlPort:txPort shape before parsing\nboolean validShape(String entry) {\n    String[] parts = entry.split(\":\");\n    return parts.length == 3 && !parts[0].isEmpty() && !parts[1].isEmpty() && !parts[2].isEmpty();\n}","typeGuard":null,"tryCatchPattern":"try {\n    node.createExternalEndpoints(external);\n} catch (ParseEndpointException e) {\n    if (e.getMessage().startsWith(\"Invalid format\")) {\n        // entry had wrong number of colon-separated parts; show expected host:ctrl:tx format\n    }\n    throw e;\n}","preventionTips":["Always specify both controller and transaction ports for every external endpoint.","No trailing commas; one entry per node; use hostnames rather than IPv6 addresses.","Document the exact format next to the property in deployment configs."],"tags":["configuration","endpoint","parsing","seata-server"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}