pentaho/pentaho-kettle · error · KettleException

There was an error preparing the transformation for…

Error message

There was an error preparing the transformation for excution on the remote server:

What it means

Thrown by Trans when preparing a transformation for clustered/remote execution: the slave server was asked (via PrepareExecutionTransServlet over Carte) to prepare the transformation and its WebResult reported a non-OK result. The remote side failed during prepareExecutionTrans, and the remote message is appended after Const.CR. It means the transformation XML was delivered but the remote node could not stage it for execution.

Solutions

Read the appended webResult.getMessage() (and the slave's carte.log) to see the remote cause
Verify the slave has all required plugins/steps installed (KETTLE_PLUGIN_PACKAGES / plugins dir)
Confirm the transformation name and carteObjectId match what was registered on the slave
Check slave DB connections, variables, and metastore availability on the remote node
Upgrade both master and slave to matching Pentaho/Kettle versions

Example fix

// before: blind clustered execution
trans.executeClustered(clusterMeta, executionConfiguration);
// after: pre-check slave connectivity and log the remote message
try {
  trans.executeClustered(clusterMeta, executionConfiguration);
} catch (KettleException e) {
  logError("Remote prepare failed: " + e.getMessage()); // includes slave webResult message
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (slaveServer.getHostname() == null || slaveServer.getHostname().isEmpty()) throw new KettleException("No slave hostname configured");
SlaveServerStatus status = slaveServer.getStatus();

Type guard

boolean isSlaveReachable(SlaveServer s) { try { return s.getStatus() != null; } catch (Exception e) { return false; } }

Try / catch

try { trans.executeClustered(clusterMeta, execConfig); } catch (KettleException e) { log.error("Remote prepare failed, slave message: " + e.getMessage(), e); /* inspect carte.log on slave */ }

Prevention

Keep master and slave plugin directories in sync
Check slave /kettle/status/ before cluster runs
Monitor slave carte.log during cluster executions

When it happens

Trigger: Calling Trans.executeProgged/clustered run path that calls slaveServer.execService(PrepareExecutionTransServlet.CONTEXT_PATH + ...) where webResult.getResult() != STRING_OK.

Common situations: Remote Carte slave missing step/plugin jars referenced by the trans; transformation name mismatch or transMeta name not registered remotely; slave-side variable/DB connection resolution failures; corrupted XML round-trip via the servlet.

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

Appendix: source

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

        //
        String xml = new TransConfiguration( transMeta, executionConfiguration ).getXML();
        String reply = slaveServer.sendXML( xml, RegisterTransServlet.CONTEXT_PATH + "/?xml=Y" );
        WebResult webResult = WebResult.fromXMLString( reply );
        if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {
          throw new KettleException( "There was an error posting the transformation on the remote server: " + Const.CR
            + webResult.getMessage() );
        }
        carteObjectId = webResult.getId();
      }

      // Prepare the transformation
      //
      String reply =
        slaveServer.execService( PrepareExecutionTransServlet.CONTEXT_PATH + "/?name=" + URLEncoder.encode( transMeta
          .getName(), "UTF-8" ) + "&xml=Y&id=" + carteObjectId );
      WebResult webResult = WebResult.fromXMLString( reply );
      if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {
        throw new KettleException( "There was an error preparing the transformation for excution on the remote server: "
          + Const.CR + webResult.getMessage() );
      }

      // Start the transformation
      //
      reply =
        slaveServer.execService( StartExecutionTransServlet.CONTEXT_PATH + "/?name=" + URLEncoder.encode( transMeta
          .getName(), "UTF-8" ) + "&xml=Y&id=" + carteObjectId );
      webResult = WebResult.fromXMLString( reply );

      if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {
        throw new KettleException( "There was an error starting the transformation on the remote server: " + Const.CR
          + webResult.getMessage() );
      }

      return carteObjectId;
    } catch ( KettleException ke ) {
      throw ke;

View on GitHub (pinned to f3058517a1)