apache/incubator-seata · error · IllegalArgumentException

listen port: %s is invalid!

Error message

listen port: %s is invalid!

What it means

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.

Source

Thrown at core/src/main/java/org/apache/seata/core/rpc/netty/NettyServerBootstrap.java:134

     * Add channel pipeline last.
     *
     * @param channel  the channel
     * @param handlers the handlers
     */
    private void addChannelPipelineLast(Channel channel, ChannelHandler... handlers) {
        if (channel != null && handlers != null) {
            channel.pipeline().addLast(handlers);
        }
    }

    /**
     * use for mock
     *
     * @param listenPort the listen port
     */
    public void setListenPort(int listenPort) {
        if (listenPort <= 0) {
            throw new IllegalArgumentException("listen port: " + listenPort + " is invalid!");
        }
        this.listenPort = listenPort;
    }

    /**
     * Gets listen port.
     *
     * @return the listen port
     */
    public int getListenPort() {
        if (listenPort != 0) {
            return listenPort;
        }
        String strPort = ConfigurationFactory.getInstance().getConfig(ConfigurationKeys.SERVER_SERVICE_PORT_CAMEL);
        int port = 0;
        try {
            port = Integer.parseInt(strPort);
        } catch (NumberFormatException exx) {

View on GitHub (pinned to e01f97c6db)

Solutions

1. Set a valid port explicitly: seata server's netty listen port (default 8091) via service-port config or SEATA_PORT env
2. Check the exact config key the server reads (e.g. server.servicePort) and that its source (file/env/config-center) resolves
3. Validate the port after parsing external input and before calling setListenPort
4. If embedding, derive the port from ServerConfig and assert it is in range 1-65535

Example fix

# before
SEATA_PORT=            # empty -> parsed as 0 -> exception

# after
SEATA_PORT=8091

// embedded usage
int port = Integer.parseInt(System.getenv().getOrDefault("SEATA_PORT", "8091"));
if (port <= 0 || port > 65535) throw new IllegalArgumentException("port out of range: " + port);
bootstrap.setListenPort(port);

int parsePort(String raw, int dflt) {
    int p = (raw == null || raw.isBlank()) ? dflt : Integer.parseInt(raw.trim());
    if (p <= 0 || p > 65535) throw new IllegalArgumentException("port out of range: " + p);
    return p;
}
int port = parsePort(System.getenv("SEATA_PORT"), 8091);

boolean isValidListenPort(int port) {
    return port > 0 && port <= 65535;
}

catch (IllegalArgumentException e) {
    if (e.getMessage().contains("is invalid")) {
        // config problem: fix SEATA_PORT / service-port source and restart
    }
}

When it happens

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

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

Related errors

• URL must not be null or blank
• ip and port string cannot be empty!
• "Invalid endpoint format: " + address + ". Port must be betw
• not support config type:
• name can't be null

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/41d11c1947d62588. Report an issue: GitHub.