pentaho/pentaho-kettle · error · KettleException

An error occurred while preparing the execution of a slave…

Error message

An error occurred while preparing the execution of a slave transformation:

What it means

Thrown by Trans.prepareExecution(String[]) while setting up a clustered transformation: the master asked a slave's Carte servlet (PrepareExecutionTransServlet) to prepare its slice of the transformation, and the slave replied with a WebResult whose result is not 'OK'. The slave-side failure message is appended to this wrapper exception, so the root cause text comes from the remote slave.

Solutions

Read the appended webResult.getMessage() to find the root cause reported by the slave, and check that slave's carte.log.
Verify the slave server is reachable and the transformation definition (connections, variables) is exported to slaves (executionConfiguration set to export clustered config).
Ensure all required variables exist on slaves: declare them in the cluster schema / set them in TransExecutionConfiguration variables map.
Align Kettle versions and installed plugins on master and all slaves.
Re-run the cluster after fixing the slave-side error; consider SniffTest on a single slave first.

Example fix

// before: clustered run fails because vars are not exported
executionConfiguration.setVariables(vars);
// after: ensure variables are exported to slaves before split/prepare
executionConfiguration.setExportingClusteredTransformation(true);
executionConfiguration.setVariables(vars);
trans.execute(new String[0]);

Defensive patterns

Strategy: try-catch

Validate before calling

for (SlaveServer s : clusterSchema.getSlaveServers()) {
  if (!s.getSlaveStatus().getStatusDescription().contains("OK")) {
    throw new KettleException("Slave not healthy: " + s.getName());
  }
}
if (executionConfiguration.getVariables().isEmpty()) {
  throw new KettleException("No variables exported to slaves");
}

Try / catch

try {
  trans.prepareExecution(new String[0]);
} catch (KettleException e) {
  if (e.getMessage().contains("preparing the execution of a slave")) {
    log.error("Slave prepare failed: " + e.getMessage() + ", cause=" + e.getCause(), e);
    // inspect failing slave carte.log, then cleanup and retry
  } else throw e;
}

Prevention

Always export variables via TransExecutionConfiguration so slaves resolve them.
Health-check all slaves (getSlaveStatus) before starting a clustered run.
Keep Kettle and plugin versions identical across master and slaves.
Test the cluster schema with a small probe transformation first.

When it happens

Trigger: Calling Trans.execute/prepareExecution on a clustered (partitioned/schema-based) transformation where one slave's prepare-execution servlet call returns a non-OK WebResult, e.g. the slave failed to allocate steps, open database connections, or initialize its TransMeta slice.

Common situations: Slave cannot reach a database or shared resource used by its transformation copy; variable/parameter values missing on the slave (Internal.Cluster.* or user variables not exported); transformation name or carteObjectId no longer registered on the slave; version skew between master and slave Kettle plugins.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/Trans.java:3921

            WebResult webResult = WebResult.fromXMLString( masterReply );
            if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {
              throw new KettleException(
                "An error occurred while preparing the execution of the master transformation: " + webResult
                  .getMessage() );
            }
          }

          // Prepare the slaves
          // WG: Should these be threaded like the above initialization?
          for ( int i = 0; i < slaves.length; i++ ) {
            TransMeta slaveTrans = transSplitter.getSlaveTransMap().get( slaves[ i ] );
            String carteObjectId = carteObjectMap.get( slaveTrans );
            String slaveReply =
              slaves[ i ].execService( PrepareExecutionTransServlet.CONTEXT_PATH + "/?name=" + URLEncoder.encode(
                slaveTrans.getName(), "UTF-8" ) + "&id=" + URLEncoder.encode( carteObjectId, "UTF-8" ) + "&xml=Y" );
            WebResult webResult = WebResult.fromXMLString( slaveReply );
            if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {
              throw new KettleException( "An error occurred while preparing the execution of a slave transformation: "
                + webResult.getMessage() );
            }
          }
        }

        if ( executionConfiguration.isClusterStarting() ) {
          // Start the master...
          if ( masterSteps.size() > 0 ) { // If there is something that needs to be done on the master...
            String carteObjectId = carteObjectMap.get( master );
            String masterReply =
              masterServer.execService( StartExecutionTransServlet.CONTEXT_PATH + "/?name=" + URLEncoder.encode(
                master.getName(), "UTF-8" ) + "&id=" + URLEncoder.encode( carteObjectId, "UTF-8" ) + "&xml=Y" );
            WebResult webResult = WebResult.fromXMLString( masterReply );
            if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {
              throw new KettleException( "An error occurred while starting the execution of the master transformation: "
                + webResult.getMessage() );
            }
          }

View on GitHub (pinned to f3058517a1)