{"record":{"id":"f0e98dcf665e3d7f","repo":"pentaho/pentaho-kettle","slug":"unable-to-prepare-allocate-initialize-the-execution-of-the-f0e98d","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/singlethreader/SingleThreader.java","lineNumber":228,"sourceCode":"    } );\n\n    singleThreaderData.mappingTrans.startThreads();\n\n    // Create the executor...\n    singleThreaderData.executor = new SingleThreadedTransExecutor( singleThreaderData.mappingTrans );\n\n    // We launch the transformation in the processRow when the first row is 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 init is done.\n    //\n    try {\n      boolean ok = singleThreaderData.executor.init();\n      if ( !ok ) {\n        throw new KettleException( BaseMessages.getString(\n          PKG, \"SingleThreader.Exception.UnableToInitSingleThreadedTransformation\" ) );\n      }\n    } catch ( KettleException e ) {\n      throw new KettleException( BaseMessages.getString(\n        PKG, \"SingleThreader.Exception.UnableToPrepareExecutionOfMapping\" ), e );\n    }\n\n    // Add the mapping transformation to the active sub-transformations map in the parent transformation\n    //\n    getTrans().addActiveSubTransformation( getStepname(), singleThreaderData.mappingTrans );\n  }\n\n  void initServletConfig() {\n    TransStepUtil.initServletConfig( getTrans(), getData().getMappingTrans() );\n  }\n\n  public boolean init( StepMetaInterface smi, StepDataInterface sdi ) {\n    meta = (SingleThreaderMeta) smi;\n    setData( (SingleThreaderData) sdi );\n    SingleThreaderData singleThreaderData = getData();\n    if ( super.init( smi, sdi ) ) {\n      // First we need to load the mapping (transformation)","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/singlethreader/SingleThreader.java#L210-L246","documentation":"After attempting to init the single-threaded executor, prepareMappingExecution catches any KettleException (including the init failure) and rewraps it with the message 'Unable to prepare (allocate, initialize) the execution of the mapping (sub-transformation)', preserving the cause. It signals the SingleThreader step could not set up its sub-transformation at step initialization time.","triggerScenarios":"Any KettleException is thrown while SingleThreader.prepareMappingExecution() prepares the sub-transformation - e.g. the wrapped executor.init() failure (error 2167) or other exceptions raised during that preparation block, all rethrown as this outer exception.","commonSituations":"Same root causes as the executor init failure: misconfigured steps in the sub-transformation, unavailable connections/resources, missing variables; also any other preparation error inside prepareMappingExecution such as problems configuring the executor from the step metadata.","solutions":["Inspect the chained cause ('Caused by') - this message is only a wrapper; fix the underlying init/preparation error it reports.","Run the sub-transformation on its own to identify the failing component.","Verify the SingleThreader step metadata: mapping reference, step proxy counts (input/output), and parameter bindings.","Check environment availability (databases, files, plugins) where the transformation executes.","Confirm variables/parameters required by the sub-transformation are defined and inherited."],"exampleFix":"// Stack trace:\n// Unable to prepare (allocate, initialize) the execution of the mapping (sub-transformation)\n//   Caused by: Unable to initialize the single threaded transformation engine...\n//     Caused by: DB connection 'DW' init failed\n// after: configure 'DW' connection correctly, then re-run","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  singleThreader.init(data);\n} catch (KettleException e) {\n  // This message is a wrapper: log and surface the root cause\n  Throwable root = e;\n  while (root.getCause() != null) root = root.getCause();\n  logError(\"SingleThreader preparation failed, root cause: \" + root.getMessage(), e);\n  return false;\n}","preventionTips":["Always chase the 'Caused by' chain - this exception only wraps the real failure","Test sub-transformations independently before embedding them in SingleThreader steps","Keep environment resources (DBs, files) reachable from the execution host"],"tags":["kettle","pdi","singlethreader","sub-transformation","init-failure"],"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"}