{"record":{"id":"95e453e2257cca8f","repo":"pentaho/pentaho-kettle","slug":"mapping-exception-unabletoprepareexecutionofmapping","errorCode":"Mapping.Exception.UnableToPrepareExecutionOfMapping","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/mapping/Mapping.java","lineNumber":286,"sourceCode":"      //\n      throw new KettleException( t );\n    }\n  }\n\n\n  public void prepareMappingExecution() throws KettleException {\n    initTransFromMeta();\n    MappingData mappingData = getData();\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      mappingData.getMappingTrans().prepareExecution( getTrans().getArguments() );\n    } catch ( KettleException e ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"Mapping.Exception.UnableToPrepareExecutionOfMapping\" ),\n          e );\n    }\n\n    // Extra optional work to do for alternative execution engines...\n    //\n    switch (  mappingData.mappingTransMeta.getTransformationType() ) {\n      case Normal:\n      case SerialSingleThreaded:\n        break;\n\n      case SingleThreaded:\n        mappingData.singleThreadedTransExcecutor = new SingleThreadedTransExecutor( mappingData.getMappingTrans() );\n        if ( !mappingData.singleThreadedTransExcecutor.init() ) {\n          throw new KettleException( BaseMessages.getString( PKG,\n              \"Mapping.Exception.UnableToInitSingleThreadedTransformation\" ) );\n        }\n        break;\n      default:","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mapping/Mapping.java#L268-L304","documentation":"During Mapping.init(), the parent step allocates and initializes the sub-transformation via Trans.prepareExecution(). If that inner call throws any KettleException (e.g. a step in the mapping failed to initialize), it is re-wrapped with this message so the root cause from the sub-transformation is preserved as the cause.","triggerScenarios":"Mapping.init() -> prepareMappingExecution() -> mappingTrans.prepareExecution(...) throwing, e.g. because a step inside the sub-transformation failed init(), a database connection in the mapping is unavailable, or the sub-transformation metadata is invalid.","commonSituations":"Broken DB connections inside the sub-transformation; missing plugin step types in the mapping; invalid variable references; the referenced mapping transformation file missing or failing to load at runtime.","solutions":["Read the wrapped 'cause' exception in the stack trace — it names the actual failing step or resource inside the mapping and fix that first.","Open the sub-transformation and verify every step initializes (run it standalone).","Check database connections and environment variables/parameters used inside the mapping.","Verify the mapping transformation file path (or repository entry) resolves at runtime and the mapping runs on its own."],"exampleFix":"null","handlingStrategy":"try-catch","validationCode":"// Before run: execute the sub-transformation standalone to verify init succeeds\nTrans test = new Trans(mappingTransMeta);\ntest.prepareExecution(args); // throws early with the real root cause","typeGuard":null,"tryCatchPattern":"try {\n  mapping.init();\n} catch (KettleException e) {\n  Throwable root = e;\n  while (root.getCause() != null) root = root.getCause();\n  logError(\"Mapping prepareExecution failed: \" + root.getMessage(), root);\n}","preventionTips":["Test sub-transformations standalone before wiring them as mappings.","Verify all DB connections and variables used inside the mapping resolve in the target environment.","Keep all step plugin jars installed on every node.","Check the 'cause' chain — the true failure is always wrapped inside."],"tags":["pdi","kettle","mapping-step","sub-transformation","initialization"],"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"}