{"record":{"id":"65510c787586e8dd","repo":"pentaho/pentaho-kettle","slug":"unable-to-initialize-the-single-threaded-transformation","errorCode":null,"errorMessage":"Unable to initialize the single threaded transformation engine because one or more steps failed to initialize.","messagePattern":"Unable to initialize the single threaded transformation engine because one or more steps failed to initialize\\.","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/singlethreader/SingleThreader.java","lineNumber":224,"sourceCode":"        // Simply pass it along to the next steps after the SingleThreader\n        //\n        SingleThreader.this.putRow( rowMeta, row );\n      }\n    } );\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;","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/singlethreader/SingleThreader.java#L206-L242","documentation":"The SingleThreader step runs a sub-transformation with a special single-threaded executor. prepareMappingExecution (called from init) initializes the executor via singleThreaderData.executor.init(); if the executor returns false - meaning one or more of the sub-transformation's steps failed to initialize - a KettleException with this message is thrown.","triggerScenarios":"SingleThreader.prepareMappingExecution() calls singleThreaderData.executor.init() which returns ok=false because any step inside the sub-transformation's init() failed (bad connection, missing file reference, invalid step settings, failed database login, etc.).","commonSituations":"Sub-transformation contains a step whose initialization fails: database connection down or misconfigured, referenced file missing, variables/parameters not defined, license/plugin step not installed on the runtime environment; sub-transformation references environment-specific resources absent on the execution server.","solutions":["Check the executor's logging output just before this error - it names the step(s) whose init() failed; fix that step first.","Open the sub-transformation standalone and run/verify it to surface the failing step.","Validate database connections, file paths and variable values used inside the sub-transformation on the machine where it executes.","Confirm all plugins used by the sub-transformation are installed on the runtime environment.","Ensure required parameters/variables are passed to the SingleThreader (inherit all variables or declare them)."],"exampleFix":"// Sub-transformation's 'Table input' init fails: connection 'DW' undefined in the run configuration\n// after: add the DW database connection to the job's run configuration / define it in the environment","handlingStrategy":"try-catch","validationCode":"// Pre-flight: verify the sub-transformation initializes standalone before wiring it into the SingleThreader\nTransMeta sub = new TransMeta(mappingFile);\nTrans t = new Trans(sub);\nt.setVariable(\"...\", value); // inject required variables\n// run a dry verification in Spoon or via Trans.verify() before production","typeGuard":null,"tryCatchPattern":"try {\n  singleThreader.init(data); \n} catch (KettleException e) {\n  logError(\"Sub-transformation steps failed to initialize: \" + e.getMessage());\n  return false;\n}","preventionTips":["Run/verify the sub-transformation standalone in the target environment before wiring it","Confirm all plugins and database drivers are installed on execution servers","Pass required variables/parameters (or enable 'inherit all variables') in the SingleThreader settings"],"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"}