pentaho/pentaho-kettle · critical · KettleStepException

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

Error message

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

What it means

After validating the target slave name, BaseStep calls RemoteStep.openWriterSocket() to open the socket used to stream rows to the remote output step. An IOException is wrapped in a KettleStepException with this message. The step cannot send its output rows to the remote host.

Solutions

  1. Confirm the slave server is running and its data port is listening (telnet/nc to host:port).
  2. Correct host/port settings in the cluster schema for the remote step.
  3. Open firewall rules for Kettle cluster data ports between nodes.
  4. Retry the run after network recovery; catch KettleStepException and inspect the wrapped IOException for the root cause.

Example fix

// before: port mismatch
remoteStep.setPort("8080"); // slave listens on 8081

// after
remoteStep.setPort("8081");
Defensive patterns

Strategy: retry

Validate before calling

// Pre-check writer socket endpoint reachability
try (Socket s = new Socket()) {
  s.connect(new InetSocketAddress(remoteStep.getHostname(), remoteStep.getPort()), 3000);
} catch (IOException e) {
  throw new IllegalStateException("Writer endpoint unreachable: " + remoteStep);
}

Try / catch

try {
  trans.execute(null);
} catch (KettleStepException e) {
  if (e.getMessage().contains("Error opening writer socket")) {
    logError("Cannot write to remote step: " + e.getMessage(), e.getCause());
    // backoff and retry the clustered run
  } else { throw e; }
}

Prevention

When it happens

Trigger: openWriterSocket() throws IOException during remote output initialization — the remote slave's server socket isn't listening, the host/port is wrong, the connection is refused, or the connection drops mid-handshake.

Common situations: Slave server not started or crashed; firewall blocking the cluster data ports; wrong port in the cluster schema; network partition between master and slaves; remote step buffers already closed from a prior failed run.

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

Appendix: source

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

            + Const.INTERNAL_VARIABLE_SLAVE_SERVER_NAME + "' is not defined." );
        }
      }

      // Start threads: one per remote step to funnel the data through...
      //
      for ( RemoteStep remoteStep : remoteOutputSteps ) {
        try {
          if ( remoteStep.getTargetSlaveServerName() == null ) {
            throw new KettleStepException(
              "The target slave server name is not defined for remote output step: " + remoteStep );
          }
          BlockingRowSet rowSet = remoteStep.openWriterSocket();
          if ( log.isDetailed() ) {
            logDetailed( BaseMessages.getString( PKG, "BaseStep.Log.OpenedWriterSocketToRemoteStep", remoteStep ) );
          }
          outputRowSets.add( rowSet );
        } catch ( IOException e ) {
          throw new KettleStepException( "Error opening writer socket to remote step '" + remoteStep + "'", e );
        }
      }
    } finally {
      outputRowSetsLock.writeLock().unlock();
    }
    remoteOutputStepsInitialized = true;
  }

  /**
   * Safe mode checking.
   *
   * @param row the row
   * @throws KettleRowException the kettle row exception
   */
  protected void safeModeChecking( RowMetaInterface row ) throws KettleRowException {
    if ( row == null ) {
      return;
    }

View on GitHub (pinned to f3058517a1)