{"record":{"id":"2f879e05fc2c32ee","repo":"apache/seatunnel","slug":"socket-server-connect-failed","errorCode":"SOCKET_SERVER_CONNECT_FAILED","errorMessage":"Cannot connect to socket server at %s:%d","messagePattern":"Cannot connect to socket server at (.+?):(.+?)","errorType":"error_code","errorClass":"SocketConnectorException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-socket/src/main/java/org/apache/seatunnel/connectors/seatunnel/socket/sink/SocketClient.java","lineNumber":67,"sourceCode":"        retries = config.getMaxNumRetries();\n        maxNumRetries = config.getMaxNumRetries();\n    }\n\n    private void createConnection() throws IOException {\n        client = new Socket(hostName, port);\n        client.setKeepAlive(true);\n        client.setTcpNoDelay(true);\n\n        outputStream = client.getOutputStream();\n    }\n\n    public void open() throws IOException {\n        try {\n            synchronized (SocketClient.class) {\n                createConnection();\n            }\n        } catch (IOException e) {\n            throw new SocketConnectorException(\n                    SocketConnectorErrorCode.SOCKET_SERVER_CONNECT_FAILED,\n                    String.format(\"Cannot connect to socket server at %s:%d\", hostName, port),\n                    e);\n        }\n    }\n\n    public void write(SeaTunnelRow row) throws IOException {\n        byte[] msg = serializationSchema.serialize(row);\n        try {\n            outputStream.write(msg);\n            outputStream.flush();\n        } catch (IOException e) {\n            // if no re-tries are enable, fail immediately\n            if (maxNumRetries == 0) {\n                throw new SocketConnectorException(\n                        SocketConnectorErrorCode.SEND_MESSAGE_TO_SOCKET_SERVER_FAILED,\n                        String.format(\n                                \"Failed to send message '%s' to socket server at %s:%d. Connection re-tries are not enabled.\",","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-socket/src/main/java/org/apache/seatunnel/connectors/seatunnel/socket/sink/SocketClient.java#L49-L85","documentation":"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.","triggerScenarios":"Calling open() when createConnection() throws IOException — connection refused (nothing listening), unreachable host, or connect timeout to hostName:port.","commonSituations":"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.","solutions":["Start the socket server on hostName:port before running the job (e.g. nc -lk 9999 for tests).","Verify hostName and port in the sink config match the actual server endpoint.","Test reachability from the worker: nc -vz host port.","Check firewall/security-group rules on the server port.","Confirm DNS/hosts resolution of hostName on the SeaTunnel worker."],"exampleFix":"// before\n# terminal: job submitted with no server listening\n$ seatunnel.sh --config socket_sink.conf\n// after\n$ nc -lk 9999 &\n$ seatunnel.sh --config socket_sink.conf  # port: 9999","handlingStrategy":"retry","validationCode":"// verify the socket server accepts connections before opening the sink\ntry (Socket s = new Socket()) {\n    s.connect(new InetSocketAddress(hostName, port), 3000); // throws if refused/unreachable\n}","typeGuard":null,"tryCatchPattern":"try {\n    socketClient.open();\n} catch (SocketConnectorException e) {\n    if (e.getCode() == SocketConnectorErrorCode.SOCKET_SERVER_CONNECT_FAILED) {\n        if (attempt < MAX_RETRIES) { Thread.sleep(backoffMs); retry(); } else throw e;\n    } else throw e;\n}","preventionTips":["Start the socket server (e.g. nc -lk <port>) before submitting the sink job.","Verify hostName/port with nc -vz from the SeaTunnel worker.","Open firewall/security-group rules for the server port.","Check DNS/hosts entries for the server hostname on worker nodes."],"tags":["socket","tcp","connection","sink"],"backgroundTag":"connection-refused","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}