pentaho/pentaho-kettle · error · KettleException

There was an error starting the transformation on the…

Error message

There was an error starting the transformation on the remote server:

What it means

Thrown by Trans when starting a transformation on a remote slave server: after calling StartExecutionTransServlet on the Carte slave, the returned WebResult was not OK, so the remote start failed and the slave's message is appended. The transformation was prepared remotely but could not be launched.

Solutions

Inspect the appended webResult.getMessage() and the slave's carte.log for the startup failure
Verify the slave is still up and the trans is in a prepared state (check Carte trans status servlet)
Retry with a fresh carteObjectId (re-register/re-prepare the trans)
Check slave resources (memory, DB connectivity) that the trans needs at start
Ensure master/slave Kettle versions match

Example fix

// before
slaveServer.execService(StartExecutionTransServlet.CONTEXT_PATH + "/?name=" + name + "&xml=Y&id=" + id);
// after: verify slave health before starting
if (!slaveServer.getStatus().equalsIgnoreCase("OK")) {
  throw new KettleException("Slave not ready: " + slaveServer.getHostname());
}

Defensive patterns

Strategy: try-catch

Validate before calling

WebResult r = new WebResult(WebResult.STRING_OK, "precheck"); // or query slave status servlet first
if (!slaveServer.getStatus().equalsIgnoreCase("OK")) throw new KettleException("Slave unavailable");

Type guard

boolean isOk(WebResult w) { return w != null && WebResult.STRING_OK.equalsIgnoreCase(w.getResult()); }

Try / catch

try { trans.executeClustered(...); } catch (KettleException e) { log.error("Remote start failed: " + e.getMessage(), e); /* verify trans state on slave via /kettle/trans/status/ */ }

Prevention

Avoid long gaps between prepare and start on slaves
Set up slave health checks and restart policies
Pin matching Kettle versions on all cluster nodes

When it happens

Trigger: slaveServer.execService(StartExecutionTransServlet.CONTEXT_PATH + ...) returns a WebResult whose result != WebResult.STRING_OK.

Common situations: Slave killed or restarted between prepare and start; remote trans aborted on startup (missing resources/DB); Carte servlet rejected the request due to wrong name/id; network/proxy mangling the XML reply.

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

Appendix: source

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

      //
      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;
    } catch ( Exception e ) {
      throw new KettleException( e );
    }
  }

  /**
   * Checks whether the transformation is ready to start (i.e. execution preparation was successful)
   *
   * @return true if the transformation was prepared for execution successfully, false otherwise
   * @see org.pentaho.di.trans.Trans#prepareExecution(String[])
   */
  public boolean isReadyToStart() {

View on GitHub (pinned to f3058517a1)