apache/shardingsphere · critical · IllegalArgumentException

Invalid port `%s`.

Error message

Invalid port `%s`.

What it means

IllegalArgumentException ('Invalid port `%s`.') thrown by BootstrapArguments.getPort when the first command-line argument to ShardingSphere-Proxy is present but Integer.parseInt(args[0]) fails. Note the asymmetric behavior: a negative number does NOT throw — it returns Optional.empty() so the configured default port is used — while any non-numeric first argument aborts startup with this exception.

Source

Thrown at proxy/bootstrap/src/main/java/org/apache/shardingsphere/proxy/arguments/BootstrapArguments.java:60

    
    /**
     * Get port.
     *
     * @return port
     * @throws IllegalArgumentException illegal argument exception
     */
    public Optional<Integer> getPort() {
        if (0 == args.length) {
            return Optional.empty();
        }
        try {
            int port = Integer.parseInt(args[0]);
            if (port < 0) {
                return Optional.empty();
            }
            return Optional.of(port);
        } catch (final NumberFormatException ignored) {
            throw new IllegalArgumentException(String.format("Invalid port `%s`.", args[0]));
        }
    }
    
    /**
     * Get configuration path.
     *
     * @return configuration path
     */
    public String getConfigurationPath() {
        return args.length < 2 ? DEFAULT_CONFIG_PATH : paddingWithSlash(args[1]);
    }
    
    private String paddingWithSlash(final String pathArg) {
        StringBuilder result = new StringBuilder(pathArg);
        if (!pathArg.startsWith("/")) {
            result.insert(0, '/');
        }
        if (!pathArg.endsWith("/")) {

View on GitHub (pinned to e952770a21)

Solutions

1. Pass the port as the first argument as a plain decimal integer: `java -jar shardingsphere-proxy-bootstrap.jar 3307 conf/server.yaml`
2. If you want the port from server.yaml, omit the argument entirely rather than passing a placeholder
3. Sanitize shell scripts that build the command line (check for stray spaces or template placeholders)

Example fix

# before
java -jar shardingsphere-proxy-bootstrap.jar conf/server.yaml

# after
java -jar shardingsphere-proxy-bootstrap.jar 3307 conf/server.yaml

// start-script guard: validate argv before exec
String portArg = args.length > 0 ? args[0] : null;
if (portArg != null && !portArg.matches("\\d+")) {
    System.err.println("First argument must be a numeric port or be omitted");
    System.exit(2);
}

When it happens

Trigger: Starting the proxy as `java -jar shardingsphere-proxy-bootstrap.jar foo` (or `3307a`, `0x3307`, ` 3307` with whitespace) where args[0] cannot be parsed as an int; NumberFormatException is caught and rethrown as IllegalArgumentException.

Common situations: Passing flags in the wrong order (e.g. putting the config path first); shell quoting/whitespace issues injecting stray characters; copy-pasting a start command with a placeholder like <port> still in it.

Related errors

• Invalid path `%s`.
• Failed to start embedded Tomcat runtime.
• Unknown argument: %s
• Missing required format info in createBatch()
• 2

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/2b218dd17c4d4375. Report an issue: GitHub.