pentaho/pentaho-kettle · error · KettleException

An error occurred sending the master transformation:

Error message

An error occurred sending the master transformation:

What it means

During clustered execution, the master transformation's XML is registered on the master Carte server via RegisterTransServlet. If the server replies with a WebResult that is not OK, the message from the server is appended and thrown as a KettleException.

Solutions

  1. Read the appended webResult.getMessage() — it contains the Carte server's actual error
  2. Verify the cluster schema's master host/port and that Carte is running and reachable
  3. Check Carte authentication (carte config users/passwords) and that the registered name doesn't already exist with a conflicting ID
  4. Align PDI versions: a newer transformation XML sent to an older Carte can be rejected

Example fix

// before
SlaveServer master = new SlaveServer("master", "wrong-host", 8080, ...);
// after
SlaveServer master = new SlaveServer("master", "carte-host", 8081, "cluster", "cluster");
Defensive patterns

Strategy: validation

Validate before calling

// ping the master Carte server before clustering
SlaveServer master = clusterSchema.findMaster();
String status = master.getStatus(); // throws/indicates if Carte unreachable
if (!status.contains("" + SlaveServer.STATUS_OK)) throw new IllegalStateException("Master Carte not healthy");

Try / catch

try {
  TransSplitter splitter = Trans.executeClustered(transMeta, config);
} catch (KettleException e) {
  if (e.getMessage().startsWith("An error occurred sending the master transformation:")) {
    logError("Master Carte rejected registration: " + e.getMessage());
  } else { throw e; }
}

Prevention

When it happens

Trigger: executeClustered calls masterServer.sendXML(..., RegisterTransServlet.CONTEXT_PATH + "/?xml=Y") and the Carte reply reports failure (registration rejected, duplicate name, Carte internal error).

Common situations: Carte master not running or wrong host/port in cluster schema, transformation with the same name already registered on the master, authentication problems with Carte, transformation XML rejected server-side (version mismatch).

Related errors

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

Appendix: source

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

          variables.put( Const.INTERNAL_VARIABLE_CLUSTER_SIZE, Integer.toString( slaves.length ) );
          variables.put( Const.INTERNAL_VARIABLE_CLUSTER_MASTER, "Y" );

          // Parameters override the variables but they need to pass over the configuration too...
          //
          Map<String, String> params = transConfiguration.getTransExecutionConfiguration().getParams();
          TransMeta ot = transSplitter.getOriginalTransformation();
          for ( String param : ot.listParameters() ) {
            String value =
              Const.NVL( ot.getParameterValue( param ), Const.NVL( ot.getParameterDefault( param ), ot.getVariable(
                param ) ) );
            params.put( param, value );
          }

          String masterReply =
            masterServer.sendXML( transConfiguration.getXML(), RegisterTransServlet.CONTEXT_PATH + "/?xml=Y" );
          WebResult webResult = WebResult.fromXMLString( masterReply );
          if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {
            throw new KettleException( "An error occurred sending the master transformation: " + webResult
              .getMessage() );
          }
          carteObjectMap.put( master, webResult.getId() );
        }
      }

      // Then the slaves...
      // These are started in a background thread.
      //
      for ( int i = 0; i < slaves.length; i++ ) {
        final int index = i;

        final TransMeta slaveTrans = transSplitter.getSlaveTransMap().get( slaves[ i ] );

        if ( executionConfiguration.isClusterPosting() ) {
          Runnable runnable = new Runnable() {
            @Override
            public void run() {

View on GitHub (pinned to f3058517a1)