alibaba/Sentinel · critical · IllegalArgumentException

Illegal port: ${port}

Error message

Illegal port: ${port}

What it means

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.

Source

Thrown at sentinel-transport/sentinel-transport-netty-http/src/main/java/com/alibaba/csp/sentinel/transport/command/netty/HttpServer.java:66

    public void start() throws Exception {
        EventLoopGroup bossGroup = new NioEventLoopGroup(1);
        EventLoopGroup workerGroup = new NioEventLoopGroup();
        try {
            ServerBootstrap b = new ServerBootstrap();
            b.group(bossGroup, workerGroup)
                .channel(NioServerSocketChannel.class)
                .childHandler(new HttpServerInitializer());
            int port;
            try {
                if (StringUtil.isEmpty(TransportConfig.getPort())) {
                    CommandCenterLog.info("Port not configured, using default port: " + DEFAULT_PORT);
                    port = DEFAULT_PORT;
                } else {
                    port = Integer.parseInt(TransportConfig.getPort());
                }
            } catch (Exception e) {
                // Will cause the application exit.
                throw new IllegalArgumentException("Illegal port: " + TransportConfig.getPort());
            }
            
            int retryCount = 0;
            ChannelFuture channelFuture = null;
            // loop for an successful binding
            while (true) {
                int newPort = getNewPort(port, retryCount);
                try {
                    channelFuture = b.bind(newPort).sync();
                    TransportConfig.setRuntimePort(newPort);
                    CommandCenterLog.info("[NettyHttpCommandCenter] Begin listening at port " + newPort);
                    break;
                } catch (Exception e) {
                    TimeUnit.MILLISECONDS.sleep(30);
                    RecordLog.warn("[HttpServer] Netty server bind error, port={}, retry={}", newPort, retryCount);
                    retryCount ++;
                }
            }

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Set a clean numeric port: -Dcsp.sentinel.transport.port=8719 with no spaces, quotes, or unresolved placeholders
2. Check the effective value at startup (log TransportConfig.getPort()) when ports are injected by scripts
3. If the value comes from an env template, ensure the variable is substituted before JVM start

Example fix

# before
export CSP_SENTINEL_TRANSPORT_PORT="${PORT} "   # unresolved placeholder + space

# after
export CSP_SENTINEL_TRANSPORT_PORT=8719

// at application startup, before Sentinel init
String port = System.getProperty("csp.sentinel.transport.port", "8719");
try {
    int p = Integer.parseInt(port.trim());
    if (p < 0 || p > 65535) throw new IllegalArgumentException("port out of range");
} catch (RuntimeException e) {
    throw new IllegalStateException("Bad csp.sentinel.transport.port: '" + port + "'");
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Bad byte array
• Bad class metadata
• Invalid Value for Read Timeout set.
• You must set either 'password' or 'authorization'
• Parameter key cannot be empty

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/c1b7f093309e0eac. Report an issue: GitHub.