{"record":{"id":"3d55a1181f74dbe0","repo":"pentaho/pentaho-kettle","slug":"unable-to-prepare-allocate-initialize-the-execution-of-the","errorCode":null,"errorMessage":"Unable to prepare (allocate, initialize) the execution of the mapping (sub-transformation)","messagePattern":"Unable to prepare \\(allocate, initialize\\) the execution of the mapping \\(sub-transformation\\)","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMapping.java","lineNumber":171,"sourceCode":"    simpleMappingData.mappingTrans.setGatheringMetrics( getTrans().isGatheringMetrics() );\n\n    // Also set the name of this step in the mapping transformation for logging\n    // purposes\n    //\n    simpleMappingData.mappingTrans.setMappingStepName( getStepname() );\n\n    initServletConfig();\n\n    // We launch the transformation in the processRow when the first row is\n    // received.\n    // This will allow the correct variables to be passed.\n    // Otherwise the parent is the init() thread which will be gone once the\n    // init is done.\n    //\n    try {\n      simpleMappingData.mappingTrans.prepareExecution( getTrans().getArguments() );\n    } catch ( KettleException e ) {\n      throw new KettleException( BaseMessages.getString( PKG,\n          \"SimpleMapping.Exception.UnableToPrepareExecutionOfMapping\" ), e );\n    }\n\n    // If there is no read/write logging step set, we can insert the data from\n    // the first mapping input/output step...\n    //\n    MappingInput[] mappingInputs = simpleMappingData.mappingTrans.findMappingInput();\n    if ( mappingInputs.length == 0 ) {\n      throw new KettleException(\n        \"The simple mapping step needs one Mapping Input step to write to in the sub-transformation\" );\n    }\n    if ( mappingInputs.length > 1 ) {\n      throw new KettleException(\n        \"The simple mapping step does not support multiple Mapping Input steps to write to in the sub-transformation\" );\n    }\n    simpleMappingData.mappingInput = mappingInputs[0];\n    simpleMappingData.mappingInput.setConnectorSteps( new StepInterface[0], new ArrayList<MappingValueRename>(), null );\n","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMapping.java#L153-L189","documentation":"The Simple Mapping step hosts a sub-transformation (mapping). prepareMappingExecution calls mappingTrans.prepareExecution(...) to allocate and initialize the sub-transformation's steps; if the sub-transformation fails to initialize (KettleException), it is re-wrapped as this error so the cause must be inspected in the chained exception.","triggerScenarios":"init() -> prepareMappingExecution -> mappingTrans.prepareExecution throws because a step inside the mapping's .ktr cannot initialize (missing step plugin, bad field mappings, sub-step metadata errors).","commonSituations":"Mapping sub-transformation references steps from plugins not installed; Mapping Input/Output removed or renamed so connectors are broken; wrong arguments or parameter mapping; sub-transformation file moved.","solutions":["Read the nested cause exception in the stack trace — it names the failing sub-step","Open the mapping .ktr and fix/validate the failing step inside it","Reconnect Mapping Input/Mapping Output steps after renames","Ensure all required step plugins used by the sub-transformation are installed","Verify the sub-transformation file path/repository location is correct"],"exampleFix":"// before\nmappingPath = \"/jobs/mapping_v1.ktr\"; // file missing\n// after\nmappingPath = \"/jobs/mapping_v2.ktr\";","handlingStrategy":"try-catch","validationCode":"TransMeta subMeta = new TransMeta(mappingPath);\n// pre-load and check the sub-transformation exists and its steps resolve\nif (subMeta.getSteps().isEmpty()) throw new IllegalArgumentException(\"empty mapping\");","typeGuard":null,"tryCatchPattern":"try { trans.execute(null); } catch (KettleException e) { if (e.getMessage().contains(\"Unable to prepare\") ) { log(\"Mapping init failed: \", e.getCause()); /* inspect cause for failing sub-step */ } else throw e; }","preventionTips":["Install all plugins used by the sub-transformation","Validate the mapping .ktr opens cleanly in Spoon before wiring it","Keep mapping files with their parent jobs in the same repo/path"],"tags":["kettle","pdi","mapping","sub-transformation","init"],"backgroundTag":"module-init-failed","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"}