pentaho/pentaho-kettle · error · KettleException

An error occurred while starting the execution of the…

Error message

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

What it means

Thrown by Trans.prepareExecution(String[]) (clustered path) after preparation succeeded: the master transformation was asked to start via StartExecutionTransServlet on its own Carte server, and the returned WebResult was not 'OK'. The remote message is appended, indicating the master slice failed during startup.

Solutions

Inspect the appended webResult.getMessage() and the master's carte.log for the startup failure.
Verify cluster schema slave definitions (hostnames/ports) are correct and reachable from the master.
Run cleanup on the master/slaves before retrying, since a previous failed run can leave stale prepared transformations.
Check master database connections and variables resolve correctly at start time.
Confirm no firewall blocks Carte ports between master and slaves.

Example fix

// before: stale prepared master blocks restart
trans.execute(new String[0]);
// after: cleanup previous run then start
trans.cleanup();
trans.execute(new String[0]);

Defensive patterns

Strategy: try-catch

Validate before calling

// verify master can reach every declared slave before starting
for (SlaveServer s : clusterSchema.getSlaveServers()) {
  InetAddress.getByName(s.getHostname());
  s.getSlaveStatus(); // throws if Carte is down
}

Try / catch

try {
  trans.prepareExecution(new String[0]);
} catch (KettleException e) {
  if (e.getMessage().contains("starting the execution of the master")) {
    trans.cleanup(); // clear stale prepared state before retry
    log.error("Master start failed: " + e.getMessage(), e);
  } else throw e;
}

Prevention

Run cleanup between clustered attempts to avoid stale prepared transformations.
Verify cluster schema hostnames/ports and firewall rules up front.
Validate master DB connections resolve at start time.
Monitor master carte.log for start-phase errors.

When it happens

Trigger: Executing a clustered transformation whose master copy fails to start: the master's start-execution servlet returns an error WebResult (e.g. steps already prepared in wrong state, missing connections, initialization failure of master-only steps such as the slave-server step).

Common situations: Master can't bind/connect to slave servers defined in the cluster schema (wrong hostname/port); database connections on master misconfigured; starting a cluster twice without cleanup, leaving the master in a bad state.

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

Appendix: source

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

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

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

View on GitHub (pinned to f3058517a1)