pentaho/pentaho-kettle · error · KettleStepException

The target slave server name is not defined for remote…

Error message

The target slave server name is not defined for remote output step: " + remoteStep

What it means

During clustered-output initialization, BaseStep iterates remoteOutputSteps and requires each RemoteStep to have a target slave server name. If RemoteStep.getTargetSlaveServerName() returns null, a KettleStepException naming the remote step is thrown before any writer socket is opened. The cluster routing metadata for that remote step is incomplete.

Solutions

Set targetSlaveServerName on every RemoteStep before execution (from the corresponding SlaveServer's name).
Verify the cluster schema has all slave servers defined with valid hostnames.
Re-generate the clustered transformation configuration via TransExecutionConfiguration so remote steps get complete slave info.
Validate before execution: iterate remoteOutputSteps and fail fast with a clear message if any target slave name is null.

Example fix

// before
RemoteStep rs = new RemoteStep(host, port, ...);
// targetSlaveServerName never set

// after
rs.setTargetSlaveServerName(slaveServer.getName());

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast before execution if any remote step lacks a target slave name
for (RemoteStep rs : remoteOutputSteps) {
  if (rs.getTargetSlaveServerName() == null) {
    throw new IllegalStateException("Missing targetSlaveServerName for " + rs);
  }
}

Try / catch

try {
  trans.execute(null);
} catch (KettleStepException e) {
  if (e.getMessage().contains("target slave server name is not defined")) {
    logError("Incomplete remote step config: " + e.getMessage(), e);
  } else { throw e; }
}

Prevention

Always populate slave server entries before generating remote steps
Use TransExecutionConfiguration to build remote step metadata
Programmatically validate remote steps before starting the transformation

When it happens

Trigger: The transformation's remote output steps were built without a targetSlaveServerName — e.g. cluster schema references a slave with no host/port resolved at configuration time, or the remote step metadata was constructed programmatically without setting the slave name.

Common situations: Programmatically composing clustered executions (TransExecutionConfiguration) without filling in target slave names; missing/removed slave server entries in the repository; cluster schema misconfiguration where a step's target slave is undefined.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

    outputRowSetsLock.writeLock().lock();
    try {
      // Set the current slave target name on all the current output steps (local)
      //
      for ( RowSet rowSet : outputRowSets ) {
        rowSet.setRemoteSlaveServerName( getVariable( Const.INTERNAL_VARIABLE_SLAVE_SERVER_NAME ) );
        if ( getVariable( Const.INTERNAL_VARIABLE_SLAVE_SERVER_NAME ) == null ) {
          throw new KettleStepException( "Variable '"
            + 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;
  }

  /**

View on GitHub (pinned to f3058517a1)