What causes "Invalid endpoint port in endpoint: ${endpoint}" in apache/seatunnel?

Replace the port section with a plain decimal integer, e.g. "localhost:5800".

apache/seatunnel · error · IllegalArgumentException

Invalid endpoint port in endpoint: ${endpoint}

Error message

Invalid endpoint port in endpoint: ${endpoint}

What it means

After splitting on the last ':', the port substring is converted with Integer.parseInt. A NumberFormatException (non-numeric port text) is rethrown as IllegalArgumentException with the original endpoint and the parse exception as cause. Valid syntax is host:port where port is a decimal integer.

Source

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

    private static HostPort parseHostAndPort(String endpoint) {
        Objects.requireNonNull(endpoint, "endpoint");
        String trimmed = endpoint.trim();
        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)

Solutions

Replace the port section with a plain decimal integer, e.g. "localhost:5800".
Resolve any unresolved config placeholders so the port is numeric in the rendered file.
Strip whitespace, commas, or units (e.g. '8080/tcp') from the port text.
Check the IllegalArgumentException cause (NumberFormatException) in logs to see the exact bad port text.

Example fix

// before
transport.endpoint = "localhost:${PORT}"

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

Defensive patterns

Strategy: validation

Validate before calling

String endpoint = cfg.getString("transport.endpoint").trim();
String portText = endpoint.substring(endpoint.lastIndexOf(':') + 1);
try {
    Integer.parseInt(portText);
} catch (NumberFormatException e) {
    throw new IllegalStateException("Port in transport.endpoint must be numeric, got: " + portText, e);
}

Type guard

boolean hasNumericPort(String endpoint) {
    String port = endpoint.substring(endpoint.lastIndexOf(':') + 1).trim();
    return port.chars().allMatch(Character::isDigit) && !port.isEmpty();
}

Try / catch

try {
    EdgeTransportEndpoints.validateFormat(endpoint);
} catch (IllegalArgumentException e) {
    if (e.getCause() instanceof NumberFormatException) {
        LOG.error("Non-numeric port in endpoint: " + endpoint, e);
    }
    throw e;
}

Prevention

Never put service names or placeholders in the port position; resolve them first.
Render configs through a strict templater that substitutes numeric ports only.
Trim whitespace and split multi-port lists before configuring a single endpoint.
Log the raw endpoint string when validation fails to spot unrendered placeholders.

When it happens

Trigger: Calling hostPort/validateFormat with an endpoint whose port section is non-numeric, e.g. "localhost:http", "host:5800x", or "host:80,90".

Common situations: Pasting a service name instead of a port; placeholder not substituted ("host:${PORT}" with a bad render); whitespace or comma-separated port lists; copying "host:port" literally from docs.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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