{"record":{"id":"7c2362d1f33ac468","repo":"pentaho/pentaho-kettle","slug":"an-error-occurred-while-starting-the-execution-of-the-master","errorCode":null,"errorMessage":"An error occurred while starting the execution of the master transformation: ","messagePattern":"An error occurred while starting 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":3936,"sourceCode":"                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            }\n          }\n        }\n\n        if ( executionConfiguration.isClusterStarting() ) {\n          // Start 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( StartExecutionTransServlet.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( \"An error occurred while starting the execution of the master transformation: \"\n                + webResult.getMessage() );\n            }\n          }\n\n          // Start 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( StartExecutionTransServlet.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 starting the execution of a slave transformation: \"\n                + webResult.getMessage() );\n            }\n          }","sourceCodeStart":3918,"sourceCodeEnd":3954,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/Trans.java#L3918-L3954","documentation":"Thrown by Trans.prepareExecution(String[]) (clustered path) after preparation succeeded: the master transformation was asked to start via StartExecutionTransServlet on its own Carte server, and the returned WebResult was not 'OK'. The remote message is appended, indicating the master slice failed during startup.","triggerScenarios":"Executing a clustered transformation whose master copy fails to start: the master's start-execution servlet returns an error WebResult (e.g. steps already prepared in wrong state, missing connections, initialization failure of master-only steps such as the slave-server step).","commonSituations":"Master can't bind/connect to slave servers defined in the cluster schema (wrong hostname/port); database connections on master misconfigured; starting a cluster twice without cleanup, leaving the master in a bad state.","solutions":["Inspect the appended webResult.getMessage() and the master's carte.log for the startup failure.","Verify cluster schema slave definitions (hostnames/ports) are correct and reachable from the master.","Run cleanup on the master/slaves before retrying, since a previous failed run can leave stale prepared transformations.","Check master database connections and variables resolve correctly at start time.","Confirm no firewall blocks Carte ports between master and slaves."],"exampleFix":"// before: stale prepared master blocks restart\ntrans.execute(new String[0]);\n// after: cleanup previous run then start\ntrans.cleanup();\ntrans.execute(new String[0]);","handlingStrategy":"try-catch","validationCode":"// verify master can reach every declared slave before starting\nfor (SlaveServer s : clusterSchema.getSlaveServers()) {\n  InetAddress.getByName(s.getHostname());\n  s.getSlaveStatus(); // throws if Carte is down\n}","typeGuard":null,"tryCatchPattern":"try {\n  trans.prepareExecution(new String[0]);\n} catch (KettleException e) {\n  if (e.getMessage().contains(\"starting the execution of the master\")) {\n    trans.cleanup(); // clear stale prepared state before retry\n    log.error(\"Master start failed: \" + e.getMessage(), e);\n  } else throw e;\n}","preventionTips":["Run cleanup between clustered attempts to avoid stale prepared transformations.","Verify cluster schema hostnames/ports and firewall rules up front.","Validate master DB connections resolve at start time.","Monitor master carte.log for start-phase errors."],"tags":["kettle","clustered-transformation","master","carte"],"backgroundTag":"http-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"}