{"record":{"id":"41d11c1947d62588","repo":"apache/incubator-seata","slug":"listen-port-s-is-invalid","errorCode":null,"errorMessage":"listen port: %s is invalid!","messagePattern":"listen port: (.+?) is invalid!","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/seata/core/rpc/netty/NettyServerBootstrap.java","lineNumber":134,"sourceCode":"     * Add channel pipeline last.\n     *\n     * @param channel  the channel\n     * @param handlers the handlers\n     */\n    private void addChannelPipelineLast(Channel channel, ChannelHandler... handlers) {\n        if (channel != null && handlers != null) {\n            channel.pipeline().addLast(handlers);\n        }\n    }\n\n    /**\n     * use for mock\n     *\n     * @param listenPort the listen port\n     */\n    public void setListenPort(int listenPort) {\n        if (listenPort <= 0) {\n            throw new IllegalArgumentException(\"listen port: \" + listenPort + \" is invalid!\");\n        }\n        this.listenPort = listenPort;\n    }\n\n    /**\n     * Gets listen port.\n     *\n     * @return the listen port\n     */\n    public int getListenPort() {\n        if (listenPort != 0) {\n            return listenPort;\n        }\n        String strPort = ConfigurationFactory.getInstance().getConfig(ConfigurationKeys.SERVER_SERVICE_PORT_CAMEL);\n        int port = 0;\n        try {\n            port = Integer.parseInt(strPort);\n        } catch (NumberFormatException exx) {","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/rpc/netty/NettyServerBootstrap.java#L116-L152","documentation":"IllegalArgumentException from NettyServerBootstrap.setListenPort: the server bootstrap rejects any listen port <= 0. The setter is used both from configuration and from tests/mocks; passing an unset (0-default from an int that failed to parse) or negative port fails fast with this message.","triggerScenarios":"Calling setListenPort(port) with port <= 0 — typically because the port was parsed from a config value that was missing or non-numeric and defaulted to 0.","commonSituations":"seata.server.service-port / server.port config key missing or misspelled; env var SEATA_PORT empty causing parse-to-0; port property read from the wrong config source; custom embedding of the seata server passing an unvalidated port.","solutions":["Set a valid port explicitly: seata server's netty listen port (default 8091) via service-port config or SEATA_PORT env","Check the exact config key the server reads (e.g. server.servicePort) and that its source (file/env/config-center) resolves","Validate the port after parsing external input and before calling setListenPort","If embedding, derive the port from ServerConfig and assert it is in range 1-65535"],"exampleFix":"# before\nSEATA_PORT=            # empty -> parsed as 0 -> exception\n\n# after\nSEATA_PORT=8091\n\n// embedded usage\nint port = Integer.parseInt(System.getenv().getOrDefault(\"SEATA_PORT\", \"8091\"));\nif (port <= 0 || port > 65535) throw new IllegalArgumentException(\"port out of range: \" + port);\nbootstrap.setListenPort(port);","handlingStrategy":"validation","validationCode":"int parsePort(String raw, int dflt) {\n    int p = (raw == null || raw.isBlank()) ? dflt : Integer.parseInt(raw.trim());\n    if (p <= 0 || p > 65535) throw new IllegalArgumentException(\"port out of range: \" + p);\n    return p;\n}\nint port = parsePort(System.getenv(\"SEATA_PORT\"), 8091);","typeGuard":"boolean isValidListenPort(int port) {\n    return port > 0 && port <= 65535;\n}","tryCatchPattern":"catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"is invalid\")) {\n        // config problem: fix SEATA_PORT / service-port source and restart\n    }\n}","preventionTips":["Default the port explicitly (8091) instead of relying on 0-sentinel parsing","Fail config loading loudly when port fields are blank or non-numeric","Smoke-test config rendering in CI for containerized seata-server"],"tags":["config","server","port","validation"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}