pentaho/pentaho-kettle · error · KettleException

An error occurred while starting the execution of a slave…

Error message

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

What it means

Thrown by Trans.prepareExecution(String[]) in the clustered path: after the master started, each slave is started via StartExecutionTransServlet, and a slave replied with a non-OK WebResult. The slave's own error message is appended to this wrapper exception.

Solutions

Check the appended webResult.getMessage() and the failing slave's carte.log for the start failure.
Verify the slave's Carte instance was not restarted between prepare and start phases; re-run the whole cluster execution if it was.
Confirm slave database connections and variables are valid and reachable.
Ensure network stability between master and slaves during execution (timeouts, firewall).
Keep master and slave Kettle/plugin versions in sync to avoid start-time incompatibilities.

Example fix

// before: restarting Carte on slaves mid-run causes start failures
// operationally: keep slaves up; then re-run
trans.prepareExecution(new String[0]);
trans.startThreads();
// after: guard with a pre-check that all slaves are alive
for (SlaveServer s : clusterSchema.findSlaveServers()) {
  if (!s.getSlaveStatus().getStatusDescription().contains("OK")) throw new KettleException("Slave down: " + s);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure all slaves are alive and registered right before start
for (SlaveServer s : clusterSchema.getSlaveServers()) {
  if (s.getSlaveStatus() == null) throw new KettleException("Slave down: " + s.getName());
}

Try / catch

try {
  trans.prepareExecution(new String[0]);
  trans.startThreads();
} catch (KettleException e) {
  if (e.getMessage().contains("starting the execution of a slave")) {
    log.error("Slave start failed: " + e.getMessage(), e);
    // re-run the entire clustered execution (prepare+start must be consistent)
  } else throw e;
}

Prevention

Do not restart slave Carte instances between prepare and start.
Avoid concurrent cleanup during a running cluster.
Keep network sessions stable; increase timeouts if slaves are slow.
Sync Kettle/plugin versions across all nodes.

When it happens

Trigger: Executing a clustered transformation where a slave's start-execution servlet call returns an error WebResult because the slave slice failed to start (e.g. step init failed, resource unavailable, transformation not found under the given carte id).

Common situations: Slave lost its prepared transformation (Carte restarted between prepare and start); slave cannot connect to its database; master/slave network partition after prepare; concurrent cleanup removed the transformation before start.

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

Appendix: source

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

                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() );
            }
          }

          // Start 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( StartExecutionTransServlet.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 starting the execution of a slave transformation: "
                + webResult.getMessage() );
            }
          }
        }
      }
    } catch ( KettleException ke ) {
      throw ke;
    } catch ( Exception e ) {
      throw new KettleException( "There was an error during transformation split", e );
    }
  }

  /**
   * Monitors a clustered transformation every second, after all the transformations in a cluster schema are running.
   * <br>
   * Now we should verify that they are all running as they should.<br>
   * If a transformation has an error, we should kill them all.<br>
   * This should happen in a separate thread to prevent blocking of the UI.<br>

View on GitHub (pinned to f3058517a1)