{"record":{"id":"f1651501f0ec4898","repo":"apache/incubator-seata","slug":"invalid-port-number-in","errorCode":null,"errorMessage":"Invalid port number in: {}","messagePattern":"Invalid port number in: (.+?)","errorType":"validation","errorClass":"ParseEndpointException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/org/apache/seata/common/metadata/Node.java","lineNumber":217,"sourceCode":"\n    private Node.ExternalEndpoint createExternalEndpoint(String host, int controllerPort, int transactionPort) {\n        return new Node.ExternalEndpoint(host, controllerPort, transactionPort);\n    }\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;","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/common/src/main/java/org/apache/seata/common/metadata/Node.java#L199-L235","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Correct the reported entry to exactly host:numericControllerPort:numericTransactionPort.","Remove stray characters/spaces/units from port fields.","For IPv6 hosts, use the hostname or wrap per your seata version's supported syntax — the naive split(\":\") only supports 3 colon-separated parts.","Validate the whole property with a regex before restart (see defense)."],"exampleFix":"# before\nexternal.endpoints=e1.seata.io:7091:8O91   # letter O instead of zero\n\n# after\nexternal.endpoints=e1.seata.io:7091:8091","handlingStrategy":"validation","validationCode":"// Validate external endpoints config before server bootstrap\nprivate static final Pattern ENDPOINT = Pattern.compile(\"^[^,:]+:\\\\d{1,5}:\\\\d{1,5}$\");\nvoid validateExternalEndpoints(String external) {\n    for (String s : external.split(\",\", -1)) {\n        if (!ENDPOINT.matcher(s.trim()).matches())\n            throw new IllegalArgumentException(\"Bad external endpoint entry: \" + s);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    List<Node.ExternalEndpoint> eps = node.createExternalEndpoints(external);\n} catch (ParseEndpointException e) {\n    // message contains the exact malformed entry; reject config with a clear startup error\n    throw new IllegalArgumentException(\"server.external-endpoints misconfigured: \" + e.getMessage(), e);\n}","preventionTips":["Use host:port:port format with numeric ports only; avoid IPv6 literals here.","Add a config lint for external-endpoints in deployment pipelines.","Keep port values within 0-65535 and free of units/whitespace."],"tags":["configuration","endpoint","parsing","seata-server"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}