apache/seatunnel · critical · SocketConnectorException

SOCKET_SERVER_CONNECT_FAILED

SOCKET_SERVER_CONNECT_FAILED

Error message

Cannot connect to socket server at %s:%d

What it means

SocketClient.open() establishes the TCP connection to the configured socket server (synchronized on SocketClient.class to serialize connection creation). Any IOException from createConnection() is rethrown as SocketConnectorException with SOCKET_SERVER_CONNECT_FAILED, naming host and port. The sink cannot send data until a connection succeeds.

Solutions

1. Start the socket server on hostName:port before running the job (e.g. nc -lk 9999 for tests).
2. Verify hostName and port in the sink config match the actual server endpoint.
3. Test reachability from the worker: nc -vz host port.
4. Check firewall/security-group rules on the server port.
5. Confirm DNS/hosts resolution of hostName on the SeaTunnel worker.

Example fix

// before
# terminal: job submitted with no server listening
$ seatunnel.sh --config socket_sink.conf
// after
$ nc -lk 9999 &
$ seatunnel.sh --config socket_sink.conf  # port: 9999

// verify the socket server accepts connections before opening the sink
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(hostName, port), 3000); // throws if refused/unreachable
}

try {
    socketClient.open();
} catch (SocketConnectorException e) {
    if (e.getCode() == SocketConnectorErrorCode.SOCKET_SERVER_CONNECT_FAILED) {
        if (attempt < MAX_RETRIES) { Thread.sleep(backoffMs); retry(); } else throw e;
    } else throw e;
}

When it happens

Trigger: Calling open() when createConnection() throws IOException — connection refused (nothing listening), unreachable host, or connect timeout to hostName:port.

Common situations: Socket server not started before the SeaTunnel job (classic: netcat/server absent on the port); wrong port in sink config; hostname not resolvable from the worker; firewall between worker and server; server crashed between jobs.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• CONNECT_DATABASE_FAILED
• CONNECT_FAILED
• CONNECTION_FAILED
• IotdbConnectorErrorCode.INITIALIZE_CLIENT_FAILED
• Airtable API rate limit reached, retry

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-socket/src/main/java/org/apache/seatunnel/connectors/seatunnel/socket/sink/SocketClient.java:67

        retries = config.getMaxNumRetries();
        maxNumRetries = config.getMaxNumRetries();
    }

    private void createConnection() throws IOException {
        client = new Socket(hostName, port);
        client.setKeepAlive(true);
        client.setTcpNoDelay(true);

        outputStream = client.getOutputStream();
    }

    public void open() throws IOException {
        try {
            synchronized (SocketClient.class) {
                createConnection();
            }
        } catch (IOException e) {
            throw new SocketConnectorException(
                    SocketConnectorErrorCode.SOCKET_SERVER_CONNECT_FAILED,
                    String.format("Cannot connect to socket server at %s:%d", hostName, port),
                    e);
        }
    }

    public void write(SeaTunnelRow row) throws IOException {
        byte[] msg = serializationSchema.serialize(row);
        try {
            outputStream.write(msg);
            outputStream.flush();
        } catch (IOException e) {
            // if no re-tries are enable, fail immediately
            if (maxNumRetries == 0) {
                throw new SocketConnectorException(
                        SocketConnectorErrorCode.SEND_MESSAGE_TO_SOCKET_SERVER_FAILED,
                        String.format(
                                "Failed to send message '%s' to socket server at %s:%d. Connection re-tries are not enabled.",

View on GitHub (pinned to cf67b549a7)