pentaho/pentaho-kettle · error · KettleException

Unable to run clean-up on slave server '

Error message

Unable to run clean-up on slave server '

What it means

Thrown by Trans's slave cleanup helper (executed during clustered run cleanup): the call to SlaveServer.cleanupTransformation(name, carteObjectId) succeeded over HTTP but returned a WebResult that is not 'OK', meaning the slave refused or failed the cleanup for that transformation.

Solutions

  1. Read the appended webResult.getMessage() to see the slave's cleanup error and the slave's carte.log.
  2. Verify the transformation was actually prepared/started on that slave (matching name and carte object id).
  3. If the slave was restarted, the transformation is already gone; treat the cleanup miss as benign or restart Carte cleanly.
  4. Check the slave has write permissions to its temp/internal directories.
  5. Re-run the full clustered execution to get consistent ids across master and slaves.

Example fix

// before: blindly cleaning up a possibly-dead slave
slaveServer.cleanupTransformation(transName, carteObjectId);
// after: verify registration first
SlaveServerTransStatus st = slaveServer.getTransStatus(transName, carteObjectId, 0);
if (st != null) slaveServer.cleanupTransformation(transName, carteObjectId);
Defensive patterns

Strategy: try-catch

Validate before calling

// only clean up a transformation that still exists on the slave
SlaveServerTransStatus st = slaveServer.getTransStatus(transName, carteObjectId, 0);
boolean exists = st != null;

Try / catch

try {
  trans.cleanup(); // conceptual guard around clustered cleanup path
} catch (KettleException e) {
  if (e.getMessage().contains("Unable to run clean-up on slave server")) {
    log.warn("Slave cleanup failed (id may be gone): " + e.getMessage());
    // treat as non-fatal: transformation likely already removed
  } else throw e;
}

Prevention

When it happens

Trigger: During cleanup of a clustered transformation, a slave's cleanup servlet responds non-OK: the transformation name/id is not registered on the slave, or the slave's internal cleanup (removing logging entries, temp files,_kettle internal files) failed.

Common situations: Carte restarted on the slave so the transformation id no longer exists; cleanup invoked twice; permissions problems on the slave removing temp/transaction files; name mismatch because TransMeta was renamed after registration.

Related errors

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

Appendix: source

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

    return errors;
  }

  /**
   * Cleanup the slave server as part of a clustered transformation.
   *
   * @param transSplitter  the TransSplitter object
   * @param slaveServer    the slave server
   * @param slaveTransMeta the slave transformation meta-data
   * @throws KettleException if any errors occur during cleanup
   */
  public static void cleanupSlaveServer( TransSplitter transSplitter, SlaveServer slaveServer,
                                         TransMeta slaveTransMeta ) throws KettleException {
    String transName = slaveTransMeta.getName();
    try {
      String carteObjectId = transSplitter.getCarteObjectMap().get( slaveTransMeta );
      WebResult webResult = slaveServer.cleanupTransformation( transName, carteObjectId );
      if ( !WebResult.STRING_OK.equals( webResult.getResult() ) ) {
        throw new KettleException( "Unable to run clean-up on slave server '" + slaveServer + "' for transformation '"
          + transName + "' : " + webResult.getMessage() );
      }
    } catch ( Exception e ) {
      throw new KettleException( "Unexpected error contacting slave server '" + slaveServer
        + "' to clear up transformation '" + transName + "'", e );
    }
  }

  /**
   * Gets the clustered transformation result.
   *
   * @param log           the log channel interface
   * @param transSplitter the TransSplitter object
   * @param parentJob     the parent job
   * @return the clustered transformation result
   */
  public static final Result getClusteredTransformationResult( LogChannelInterface log, TransSplitter transSplitter,
                                                               Job parentJob ) {

View on GitHub (pinned to f3058517a1)