pentaho/pentaho-kettle · critical · KettleStepException

Error opening reader socket to remote step '" + remoteStep…

Error message

Error opening reader socket to remote step '" + remoteStep + "'

What it means

When a step in a clustered transformation consumes data from remote input steps, BaseStep calls RemoteStep.openReaderSocket(this) for each remote input to open the socket that feeds rows in. Any exception while opening a reader socket is wrapped in a KettleStepException with this message. The step cannot receive its input rows from the remote host.

Solutions

  1. Verify each slave server is up and reachable (telnet/nc to its hostname and port from the master).
  2. Check cluster schema host/port configuration and correct any wrong hostnames.
  3. Open firewall ports used by Kettle cluster communication.
  4. Retry the clustered run after confirming slaves have fully started; catch KettleStepException and log the wrapped cause for the root network error.

Example fix

// before: slave defined as 'slave01' which does not resolve
clusterSchema.getSlaves().get(0).setHostname("slave01");

// after: use resolvable hostname/IP and verified port
clusterSchema.getSlaves().get(0).setHostname("192.168.1.10");
clusterSchema.getSlaves().get(0).setPort("8081");
Defensive patterns

Strategy: validation

Validate before calling

// Pre-check slave reachability before clustered execution
for (SlaveServer slave : clusterSchema.getSlaves()) {
  if (!slave.getHostname().equals("localhost") &&
      !InetAddress.getByName(slave.getHostname()).isReachable(3000)) {
    throw new IllegalStateException("Slave unreachable: " + slave.getHostname());
  }
}

Try / catch

try {
  trans.execute(null);
} catch (KettleStepException e) {
  if (e.getMessage().contains("Error opening reader socket")) {
    logError("Cannot read from remote step: " + e.getMessage(), e.getCause());
    // retry or abort the clustered run
  } else { throw e; }
}

Prevention

When it happens

Trigger: openReaderSocket throws during initialization of remote input steps (remoteInputSteps loop) — network failure, remote slave not listening on the expected port, hostname unresolvable, or the remote step hasn't started its server socket.

Common situations: Firewall blocking cluster ports between master and slaves; slave server down or restarting; wrong host/port in cluster schema; DNS resolution failure for slave hostnames; starting clustered run before slaves are ready.

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

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/step/BaseStep.java:2042

  protected void openRemoteInputStepSocketsOnce() throws KettleStepException {
    if ( remoteInputSteps.isEmpty()
      || remoteInputStepsInitialized ) {

      return;
    }

    // Loop over the remote steps and open client sockets to them
    // Just be careful in case we're dealing with a partitioned clustered step.
    // A partitioned clustered step has only one. (see dispatch())
    //
    inputRowSetsLock.writeLock().lock();
    try {
      for ( RemoteStep remoteStep : remoteInputSteps ) {
        try {
          BlockingRowSet rowSet = remoteStep.openReaderSocket( this );
          inputRowSets.add( rowSet );
        } catch ( Exception e ) {
          throw new KettleStepException( "Error opening reader socket to remote step '" + remoteStep + "'", e );
        }
      }
    } finally {
      inputRowSetsLock.writeLock().unlock();
    }
    remoteInputStepsInitialized = true;
  }

  /**
   * Opens socket connections to the remote output steps of this step. <br>
   * This method is called in method initBeforeStart() because it needs to connect to the server sockets (remote steps)
   * as soon as possible to avoid time-out situations. <br>
   * This action is executed only once.
   *
   * @throws KettleStepException if there is an error opening socket connections to the remote output steps
   */
  protected void openRemoteOutputStepSocketsOnce() throws KettleStepException {
    if ( remoteOutputSteps.isEmpty()

View on GitHub (pinned to f3058517a1)