apache/seatunnel · error · IllegalArgumentException

transport.endpoint port must be a valid TCP port (1-65535)…

Error message

transport.endpoint port must be a valid TCP port (1-65535), got: ${port}

What it means

Once the port parses as an integer, parseHostAndPort enforces the TCP port range: it must be between 1 and 65535 inclusive. Ports 0 or >65535 throw IllegalArgumentException telling the caller the required valid TCP port range and the value received.

Solutions

Use a port in 1-65535, e.g. "host:5800".
If you intended an ephemeral/auto-assigned port, pick an explicit port instead — this parser requires one.
Verify the value source (env var, script arithmetic) yields a number within range.
Check for duplicated digits or concatenation mistakes in generated configs.

Example fix

// before
transport.endpoint = "localhost:70000"

// after
transport.endpoint = "localhost:5800"

Defensive patterns

Strategy: validation

Validate before calling

int port = Integer.parseInt(cfg.getString("transport.endpoint").substring(cfg.getString("transport.endpoint").lastIndexOf(':') + 1));
if (port < 1 || port > 65535) {
    throw new IllegalStateException("transport.endpoint port must be 1-65535, got: " + port);
}

Type guard

boolean isValidTcpPort(int port) { return port >= 1 && port <= 65535; }

Try / catch

try {
    EdgeTransportEndpoints.validateFormat(endpoint);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("valid TCP port")) {
        LOG.error("Port out of range in endpoint: " + endpoint, e);
    }
    throw e;
}

Prevention

Clamp or assert port values in the script that generates agent configs.
Reject port 0 explicitly — this parser does not support auto-assignment.
Range-check ports read from env vars before interpolating them into configs.
Keep a checklist of valid port ranges for your deployment environment.

When it happens

Trigger: Calling hostPort/validateFormat with endpoints like "host:0", "host:70000", or "host:-1" — syntactically numeric but outside 1..65535.

Common situations: Using 0 to mean 'auto-assign' (not supported here); fat-fingering digits to exceed 65535; copy-pasting a container-internal ephemeral range value; negative numbers from subtraction in templated values.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/08ce9397b2ab9a99. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-transport/src/main/java/org/apache/seatunnel/edge/agent/transport/config/EdgeTransportEndpoints.java:62

        if (trimmed.isEmpty()) {
            throw new IllegalArgumentException("transport.endpoint must be non-empty.");
        }
        int separatorIndex = trimmed.lastIndexOf(':');
        if (separatorIndex <= 0 || separatorIndex >= trimmed.length() - 1) {
            throw new IllegalArgumentException(
                    "Invalid endpoint: " + endpoint + ", expected format host:port");
        }
        String host = trimmed.substring(0, separatorIndex);
        String portText = trimmed.substring(separatorIndex + 1);
        int port;
        try {
            port = Integer.parseInt(portText);
        } catch (NumberFormatException parseException) {
            throw new IllegalArgumentException(
                    "Invalid endpoint port in endpoint: " + endpoint, parseException);
        }
        if (port < 1 || port > 65535) {
            throw new IllegalArgumentException(
                    "transport.endpoint port must be a valid TCP port (1-65535), got: " + port);
        }
        return new HostPort(host, port);
    }

    private static final class HostPort {
        private final String host;
        private final int port;

        HostPort(String host, int port) {
            this.host = host;
            this.port = port;
        }
    }
}

View on GitHub (pinned to cf67b549a7)