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

SocketReader.processRow() retries connecting to the companion SocketWriter step's host/port for a fixed timeout (TIMEOUT_IN_SECONDS). If after the timeout the connection attempt loop exits without lastException (or the stream is still null), it throws this KettleException indicating the socket handshake never completed in time.

Solutions

Confirm the SocketWriter step runs before/alongside the reader and its port matches the reader's configured port (check variable substitution values in logs).
Increase startup ordering: ensure both steps belong to the same executing transformation and the writer's 'accept' is not delayed by slow init.
Test connectivity from the reader host: telnet/nc to the writer host:port.
Check firewall/iptables/security-group rules for the chosen port.
Verify hostname resolves correctly (avoid stale /etc/hosts or wrong container DNS names).

Example fix

// before
// reader port: 8080, writer bound to 8081
// after
// set SocketReader port = SocketWriter port = 8081 in step settings

Defensive patterns

Strategy: retry

Validate before calling

try (Socket s = new Socket()) { s.connect(new InetSocketAddress(host, port), 5000); } catch (IOException e) { /* writer not reachable yet */ }

Try / catch

catch (KettleException e) {
  if (e.getMessage().contains("SocketWriter")) {
    // wait and retry the transformation once the writer step is confirmed started
  }
}

Prevention

Ensure SocketWriter initialization precedes SocketReader in execution order.
Verify host/port variables resolve identically in both steps' logs.
Pre-test port reachability with nc/telnet in clustered environments.
Keep ports out of ephemeral ranges and open them in firewalls.

When it happens

Trigger: Running a transformation where a SocketReader step's target SocketWriter is not yet started, listens on a different host/port, is blocked by a firewall, or the hostname/port variables resolve incorrectly; also when connection succeeds but the object input stream is null.

Common situations: Clustered/parallel execution ordering issues where reader starts before writer; typo in port number; localhost vs container hostname mismatch in Docker/Kubernetes; firewall dropping the port.

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/23056cb858a7b78f. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/socketreader/SocketReader.java:126

            Thread.sleep( 1000 );
          }
        }

        if ( lastException != null ) {
          logError( "Error initialising step: " + lastException.toString() );
          logError( Const.getStackTracker( lastException ) );
          if ( data.socket != null ) {
            data.socket.shutdownInput();
            data.socket.shutdownOutput();
            data.socket.close();
            logError( "Closed connection to data socket to "
              + environmentSubstitute( meta.getHostname() ) + " port " + environmentSubstitute( meta.getPort() ) );
          }

          throw lastException;
        } else {
          if ( data.inputStream == null ) {
            throw new KettleException( "Unable to connect to the SocketWriter in the "
              + TIMEOUT_IN_SECONDS + "s timeout period." );
          }
        }

        data.rowMeta = new RowMeta( data.inputStream ); // This is the metadata
        first = false;
      }
      r = data.rowMeta.readData( data.inputStream );

      incrementLinesInput();

      if ( checkFeedback( getLinesInput() ) ) {
        logBasic( BaseMessages.getString( PKG, "SocketReader.Log.LineNumber" ) + getLinesInput() );
      }

      putRow( data.rowMeta, r );
    } catch ( KettleEOFException e ) {
      setOutputDone(); // finished reading.

View on GitHub (pinned to f3058517a1)