{"record":{"id":"cbcf0c7c65abe154","repo":"pentaho/pentaho-kettle","slug":"an-error-occurred-while-preparing-the-execution-of-the","errorCode":null,"errorMessage":"An error occurred while preparing the execution of the master transformation: ","messagePattern":"An error occurred while preparing the execution of the master transformation: ","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/Trans.java","lineNumber":3905,"sourceCode":"        if ( threads[ i ] != null ) {\n          threads[ i ].join();\n          if ( errors[ i ] != null ) {\n            throw new KettleException( errors[ i ] );\n          }\n        }\n      }\n\n      if ( executionConfiguration.isClusterPosting() ) {\n        if ( executionConfiguration.isClusterPreparing() ) {\n          // Prepare the master...\n          if ( masterSteps.size() > 0 ) { // If there is something that needs to be done on the master...\n            String carteObjectId = carteObjectMap.get( master );\n            String masterReply =\n              masterServer.execService( PrepareExecutionTransServlet.CONTEXT_PATH + \"/?name=\" + URLEncoder.encode(\n                master.getName(), \"UTF-8\" ) + \"&id=\" + URLEncoder.encode( carteObjectId, \"UTF-8\" ) + \"&xml=Y\" );\n            WebResult webResult = WebResult.fromXMLString( masterReply );\n            if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {\n              throw new KettleException(\n                \"An error occurred while preparing the execution of the master transformation: \" + webResult\n                  .getMessage() );\n            }\n          }\n\n          // Prepare the slaves\n          // WG: Should these be threaded like the above initialization?\n          for ( int i = 0; i < slaves.length; i++ ) {\n            TransMeta slaveTrans = transSplitter.getSlaveTransMap().get( slaves[ i ] );\n            String carteObjectId = carteObjectMap.get( slaveTrans );\n            String slaveReply =\n              slaves[ i ].execService( PrepareExecutionTransServlet.CONTEXT_PATH + \"/?name=\" + URLEncoder.encode(\n                slaveTrans.getName(), \"UTF-8\" ) + \"&id=\" + URLEncoder.encode( carteObjectId, \"UTF-8\" ) + \"&xml=Y\" );\n            WebResult webResult = WebResult.fromXMLString( slaveReply );\n            if ( !webResult.getResult().equalsIgnoreCase( WebResult.STRING_OK ) ) {\n              throw new KettleException( \"An error occurred while preparing the execution of a slave transformation: \"\n                + webResult.getMessage() );\n            }","sourceCodeStart":3887,"sourceCodeEnd":3923,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/Trans.java#L3887-L3923","documentation":"After registering the master transformation, executeClustered asks the master Carte server to prepare it for execution via PrepareExecutionTransServlet. A non-OK WebResult (registration OK but preparation failed) is thrown as this KettleException with the server's message appended.","triggerScenarios":"executeClustered calls masterServer.execService(PrepareExecutionTransServlet.CONTEXT_PATH + \"/?name=...&id=...&xml=Y\") and the prepare call returns a failed WebResult.","commonSituations":"The transformation fails during prepareExecution on the master (bad step config, missing database connections defined only on the client, missing plugin on the Carte master), or the carteObjectId/name query params are stale/incorrect.","solutions":["Read the appended webResult.getMessage() — it reports why prepareExecution failed on the master","Check the Carte master's log for the underlying exception (missing plugin, missing DB driver, step init failure)","Ensure all plugins, drivers, and referenced resources (files, connections) exist on the Carte master machine","Verify the transformation name and carteObjectId being passed are the ones returned by registration"],"exampleFix":"// before: MySQL driver missing on Carte master, prepare fails\n// after: place mysql-connector-java.jar into Carte's lib/ and restart Carte\n// then re-run executeClustered","handlingStrategy":"try-catch","validationCode":"// confirm the master registered and plugins/drivers exist before prepare\nString masterStatus = masterServer.getStatus();\nif (!masterStatus.contains(\"OK\")) throw new IllegalStateException(\"Master Carte unhealthy before prepare\");","typeGuard":null,"tryCatchPattern":"try {\n  TransSplitter splitter = Trans.executeClustered(transMeta, config);\n} catch (KettleException e) {\n  if (e.getMessage().startsWith(\"An error occurred while preparing the execution of the master transformation:\")) {\n    logError(\"Prepare failed on master: \" + e.getMessage());\n  } else { throw e; }\n}","preventionTips":["Deploy all required plugins and JDBC drivers to the Carte master's lib/plugins directories","Ensure database connections referenced by the transformation resolve on the master host","Read webResult.getMessage() appended to the exception — it names the prepare failure","Check the master Carte log (catalina/carte log) for the full server-side stack trace"],"tags":["cluster","carte","execution"],"backgroundTag":"api-error-response","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}