pentaho/pentaho-kettle · error · KettleException

An error occurred while preparing the execution of the…

Error message

An error occurred while preparing the execution of the master transformation:

What it means

After registering the master transformation, executeClustered asks the master Carte server to prepare it for execution via PrepareExecutionTransServlet. A non-OK WebResult (registration OK but preparation failed) is thrown as this KettleException with the server's message appended.

Solutions

Read the appended webResult.getMessage() — it reports why prepareExecution failed on the master
Check the Carte master's log for the underlying exception (missing plugin, missing DB driver, step init failure)
Ensure all plugins, drivers, and referenced resources (files, connections) exist on the Carte master machine
Verify the transformation name and carteObjectId being passed are the ones returned by registration

Example fix

// before: MySQL driver missing on Carte master, prepare fails
// after: place mysql-connector-java.jar into Carte's lib/ and restart Carte
// then re-run executeClustered

Defensive patterns

Strategy: try-catch

Validate before calling

// confirm the master registered and plugins/drivers exist before prepare
String masterStatus = masterServer.getStatus();
if (!masterStatus.contains("OK")) throw new IllegalStateException("Master Carte unhealthy before prepare");

Try / catch

try {
  TransSplitter splitter = Trans.executeClustered(transMeta, config);
} catch (KettleException e) {
  if (e.getMessage().startsWith("An error occurred while preparing the execution of the master transformation:")) {
    logError("Prepare failed on master: " + e.getMessage());
  } else { throw e; }
}

Prevention

Deploy all required plugins and JDBC drivers to the Carte master's lib/plugins directories
Ensure database connections referenced by the transformation resolve on the master host
Read webResult.getMessage() appended to the exception — it names the prepare failure
Check the master Carte log (catalina/carte log) for the full server-side stack trace

When it happens

Trigger: executeClustered calls masterServer.execService(PrepareExecutionTransServlet.CONTEXT_PATH + "/?name=...&id=...&xml=Y") and the prepare call returns a failed WebResult.

Common situations: The transformation fails during prepareExecution on the master (bad step config, missing database connections defined only on the client, missing plugin on the Carte master), or the carteObjectId/name query params are stale/incorrect.

Related errors

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

Appendix: source

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

        if ( threads[ i ] != null ) {
          threads[ i ].join();
          if ( errors[ i ] != null ) {
            throw new KettleException( errors[ i ] );
          }
        }
      }

      if ( executionConfiguration.isClusterPosting() ) {
        if ( executionConfiguration.isClusterPreparing() ) {
          // Prepare 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( PrepareExecutionTransServlet.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 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() );
            }

View on GitHub (pinned to f3058517a1)