{"record":{"id":"c1b7f093309e0eac","repo":"alibaba/Sentinel","slug":"illegal-port-port","errorCode":null,"errorMessage":"Illegal port: ${port}","messagePattern":"Illegal port: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"sentinel-transport/sentinel-transport-netty-http/src/main/java/com/alibaba/csp/sentinel/transport/command/netty/HttpServer.java","lineNumber":66,"sourceCode":"    public void start() throws Exception {\n        EventLoopGroup bossGroup = new NioEventLoopGroup(1);\n        EventLoopGroup workerGroup = new NioEventLoopGroup();\n        try {\n            ServerBootstrap b = new ServerBootstrap();\n            b.group(bossGroup, workerGroup)\n                .channel(NioServerSocketChannel.class)\n                .childHandler(new HttpServerInitializer());\n            int port;\n            try {\n                if (StringUtil.isEmpty(TransportConfig.getPort())) {\n                    CommandCenterLog.info(\"Port not configured, using default port: \" + DEFAULT_PORT);\n                    port = DEFAULT_PORT;\n                } else {\n                    port = Integer.parseInt(TransportConfig.getPort());\n                }\n            } catch (Exception e) {\n                // Will cause the application exit.\n                throw new IllegalArgumentException(\"Illegal port: \" + TransportConfig.getPort());\n            }\n            \n            int retryCount = 0;\n            ChannelFuture channelFuture = null;\n            // loop for an successful binding\n            while (true) {\n                int newPort = getNewPort(port, retryCount);\n                try {\n                    channelFuture = b.bind(newPort).sync();\n                    TransportConfig.setRuntimePort(newPort);\n                    CommandCenterLog.info(\"[NettyHttpCommandCenter] Begin listening at port \" + newPort);\n                    break;\n                } catch (Exception e) {\n                    TimeUnit.MILLISECONDS.sleep(30);\n                    RecordLog.warn(\"[HttpServer] Netty server bind error, port={}, retry={}\", newPort, retryCount);\n                    retryCount ++;\n                }\n            }","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/alibaba/Sentinel/blob/a3f40ba8e900c8489bd520274739f17235a7721c/sentinel-transport/sentinel-transport-netty-http/src/main/java/com/alibaba/csp/sentinel/transport/command/netty/HttpServer.java#L48-L84","documentation":"The netty-http command center reads its listen port from TransportConfig (system property / env csp.sentinel.transport.port / -Dcsp.sentinel.transport.port). HttpServer parses it with Integer.parseInt inside a try-catch and rethrows IllegalArgumentException(\"Illegal port: ...\") on any parse failure; the comment states this intentionally causes application exit, since the command center cannot start. Only this netty transport throws; the simple-http transport just logs and falls back.","triggerScenarios":"Setting -Dcsp.sentinel.transport.port=8719x, =\"8719 \" (trailing space), or any non-numeric value while sentinel-transport-netty-http is on the classpath; Integer.parseInt throws NumberFormatException, caught, and rethrown as this error.","commonSituations":"Port placeholders from CI/CD templating (e.g. ${port} left unresolved); trailing whitespace/newline in env var values; typo in port config after an environment migration; switching transports from simple-http (lenient) to netty-http (fatal).","solutions":["Set a clean numeric port: -Dcsp.sentinel.transport.port=8719 with no spaces, quotes, or unresolved placeholders","Check the effective value at startup (log TransportConfig.getPort()) when ports are injected by scripts","If the value comes from an env template, ensure the variable is substituted before JVM start"],"exampleFix":"# before\nexport CSP_SENTINEL_TRANSPORT_PORT=\"${PORT} \"   # unresolved placeholder + space\n\n# after\nexport CSP_SENTINEL_TRANSPORT_PORT=8719","handlingStrategy":"validation","validationCode":"// at application startup, before Sentinel init\nString port = System.getProperty(\"csp.sentinel.transport.port\", \"8719\");\ntry {\n    int p = Integer.parseInt(port.trim());\n    if (p < 0 || p > 65535) throw new IllegalArgumentException(\"port out of range\");\n} catch (RuntimeException e) {\n    throw new IllegalStateException(\"Bad csp.sentinel.transport.port: '\" + port + \"'\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate injected port values in startup scripts before JVM launch","Beware unresolved ${var} placeholders and trailing whitespace from env templating"],"tags":["sentinel","transport","netty","configuration","startup"],"backgroundTag":null,"analyzedSha":"a3f40ba8e900c8489bd520274739f17235a7721c","analyzedAt":"2026-08-14T11:10:30.678Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}