pentaho/pentaho-kettle · error · KettleStepException

Variable '" + Const.INTERNAL_VARIABLE_SLAVE_SERVER_NAME +…

Error message

Variable '" + Const.INTERNAL_VARIABLE_SLAVE_SERVER_NAME + "' is not defined.

What it means

Before starting remote output threads, BaseStep sets each output rowset's remote slave name from the internal variable Const.INTERNAL_VARIABLE_SLAVE_SERVER_NAME (Internal.Slave.Server.Name). If that variable is null, a KettleStepException declaring the variable undefined is thrown. This internal variable must be set by the clustered-execution framework; its absence means the step is running outside a properly initialized clustered context.

Solutions

1. Run the transformation via the proper clustered execution path (SlaveServer/TransExecutionConfiguration) so internal variables get set.
2. Set the variable explicitly before execution: setVariable(Const.INTERNAL_VARIABLE_SLAVE_SERVER_NAME, slaveName) on the transformation.
3. Remove remote output step configuration if the transformation is meant to run standalone.
4. Guard code that calls putRow on such steps with a check that the variable is defined.

Example fix

// before: standalone run of a clustered transformation
Trans trans = new Trans(transMeta);
trans.execute(null);

// after: define the internal variable or use cluster config
trans.setVariable(Const.INTERNAL_VARIABLE_SLAVE_SERVER_NAME, "my-slave");
trans.execute(null);

String slaveName = trans.getVariable(Const.INTERNAL_VARIABLE_SLAVE_SERVER_NAME);
if (slaveName == null && transMeta.hasRemoteOutputSteps()) {
  throw new IllegalStateException("Internal.Slave.Server.Name variable is not set");
}

try {
  putRow(rowMeta, row);
} catch (KettleStepException e) {
  if (e.getMessage().contains("INTERNAL_VARIABLE_SLAVE_SERVER_NAME") ||
      e.getMessage().contains("Internal.Slave.Server.Name")) {
    logError("Slave server variable missing; not a clustered run", e);
  } else { throw e; }
}

When it happens

Trigger: A remote-output (clustered) step executes where the internal slave server name variable was never set — e.g. running the transformation directly instead of through the cluster runtime, or a Kettle version where the variable was not initialized before putRow/startThreads.

Common situations: Running a clustered transformation locally without a slave server context; older/newer Pentaho versions changing internal variable initialization; executing a step copied from a clustered transformation in a standalone transformation.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• ChangeFileEncoding.Exception.TargetEncodingEmpty
• Endless loop detected for substitution of variable:
• FileSystemConfigBuilder could not parse parameter:
• JobTrans.Exception.UnableToFindRemoteSlaveServer
• Please specify Local directory

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

Appendix: source

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

   *
   * @throws KettleStepException if there is an error opening socket connections to the remote output steps
   */
  protected void openRemoteOutputStepSocketsOnce() throws KettleStepException {
    if ( remoteOutputSteps.isEmpty()
      || remoteOutputStepsInitialized
      || stepMeta.isMappingOutput() ) { // PDI-20183 MappingOutput is configured in the Mapping step

      return;
    }

    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 ) {

View on GitHub (pinned to f3058517a1)