pentaho/pentaho-kettle · error · KettleException

Unexpected error contacting slave server '

Error message

Unexpected error contacting slave server '

What it means

Companion to the cleanup error: thrown when the actual HTTP contact with the slave during cleanupTransformation throws any Exception (connection refused, timeout, IO error). The original exception is attached as cause.

Solutions

1. Check the cause of the exception and verify the slave Carte service is up (curl its status URL).
2. Verify the slave's hostname/port/username/password in the cluster schema definition.
3. Increase timeout or retry cleanup; cleanup is idempotent on the slave side.
4. Confirm network/firewall allows master-to-slave access on the Carte port.
5. If slaves are intentionally torn down with the run, suppress or log cleanup errors instead of failing the run.

Example fix

// before: cleanup crashes when slave already stopped
slaveServer.cleanupTransformation(transName, carteObjectId);
// after: guard reachability
if (slaveServer.getSlaveStatus() != null) {
  slaveServer.cleanupTransformation(transName, carteObjectId);
}

// probe slave reachability before cleanup
if (slaveServer.getSlaveStatus() == null) {
  log.warn("Slave " + slaveServer + " unreachable; skipping cleanup");
  return;
}

try {
  slaveServer.cleanupTransformation(transName, carteObjectId);
} catch (Exception e) {
  log.warn("Cleanup contact failed, retrying once", e);
  slaveServer.cleanupTransformation(transName, carteObjectId); // idempotent
}

When it happens

Trigger: During clustered-transformation cleanup, slaveServer.cleanupTransformation() fails to reach the slave: Carte not running, wrong host/port, network outage, SSL/credentials mismatch, or timeout while the slave is busy.

Common situations: Slave server shut down before master finished cleaning up; firewall blocks the Carte port; hostname typo or DNS change; Carte authentication enabled but master lacking credentials.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Unable to run clean-up on slave server '
• An error occurred while preparing the execution of a slave…
• An error occurred while starting the execution of a slave…
• Port to close was not found in the Carte socket repository!
• A server socket allocation always has to accompanied by a…

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

Appendix: source

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

   * 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 ) {
    return getClusteredTransformationResult( log, transSplitter, parentJob, false );
  }

  /**

View on GitHub (pinned to f3058517a1)