pentaho/pentaho-kettle · error · KettleException

Unable to connect to the SocketWriter in the

Error message

Unable to connect to the SocketWriter in the {TIMEOUT_IN_SECONDS}s timeout period.

What it means

Thrown by RemoteStep.openReaderSocket after the retry loop finished without an exception but no input stream was obtained: the remote SocketWriter never accepted a connection within TIMEOUT_IN_SECONDS. The reader waited out the full timeout and gives up.

Solutions

Verify the remote slave server hostname and data port are correct and reachable (telnet/nc test).
Check the slave server log for errors preventing the SocketWriter from starting.
Open firewall rules for the cluster data ports between master and slaves.
Increase the socket timeout configuration in the cluster schema if the remote startup is slow.

Example fix

// before
String host = "slave-internal-name"; // unresolvable
// after
String host = "10.0.0.12"; // resolvable, firewalled-open slave host

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight connectivity check before opening the reader socket
try (Socket s = new Socket()) {
  s.connect(new InetSocketAddress(realHostname, portNumber), 5000); // throws if unreachable
}

Try / catch

try { remoteStep.openReaderSocket(baseStep); } catch (KettleException e) { if (e.getMessage().contains("Unable to connect to the SocketWriter")) { log.error("Remote slave " + hostname + ":" + port + " unreachable or too slow"); } else { throw e; } }

Prevention

Open cluster data ports in firewalls between master and slaves
Use resolvable, stable hostnames (or IPs) in cluster schemas
Pre-start slave servers before launching clustered transformations
Raise socket timeout settings when slaves start slowly

When it happens

Trigger: Calling openReaderSocket against a remote slave whose server socket does not start or is unreachable within TIMEOUT_IN_SECONDS seconds, exhausting all retry attempts and leaving inputStream null.

Common situations: Firewall blocking the cluster data port, wrong hostname/port in the cluster schema, slow slave-server startup, or the remote step failing before it opens its SocketWriter.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/a4cada64953bd1ee. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/step/RemoteStep.java:648

        }
      }
    }

    // See if all was OK...
    if ( lastException != null ) {

      baseStep.logError( "Error initialising step: " + lastException.toString() );
      if ( socket != null ) {
        socket.shutdownInput();
        socket.shutdownOutput();
        socket.close();
        baseStep.logDetailed( "Closed connection to server socket to read rows from remote step on server "
          + realHostname + " port " + portNumber + " - Local port=" + socket.getLocalPort() );
      }
      throw lastException;
    } else {
      if ( inputStream == null ) {
        throw new KettleException( "Unable to connect to the SocketWriter in the "
          + TIMEOUT_IN_SECONDS + "s timeout period." );
      }
    }

    baseStep.logDetailed( "Opened connection to server socket to read rows from remote step on server "
      + realHostname + " port " + portNumber + " - Local port=" + socket.getLocalPort() );

    // Create a thread to take care of the reading from the client socket.
    // The rows read will be put in a RowSet buffer.
    // That buffer will hand over the rows to the step that has this RemoteStep
    // object defined
    // as a remote input step.
    //
    Runnable runnable = new Runnable() {
      public void run() {
        try {

          // First read the row meta data from the socket...

View on GitHub (pinned to f3058517a1)