{"record":{"id":"7c216d1da95742ce","repo":"pentaho/pentaho-kettle","slug":"mapping-exception-unabletoinitsinglethreadedtransformation","errorCode":"Mapping.Exception.UnableToInitSingleThreadedTransformation","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/mapping/Mapping.java","lineNumber":300,"sourceCode":"    //\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:\n        break;\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 = mappingData.getMappingTrans().findMappingInput();\n    LogTableField readField = mappingData.mappingTransMeta.getTransLogTable().findField( TransLogTable.ID.LINES_READ );\n    if ( readField.getSubject() == null && mappingInputs != null && mappingInputs.length >= 1 ) {\n      readField.setSubject( mappingInputs[0].getStepMeta() );\n    }\n    MappingOutput[] mappingOutputs = mappingData.getMappingTrans().findMappingOutput();\n    LogTableField writeField = mappingData.mappingTransMeta.getTransLogTable().findField( TransLogTable.ID.LINES_WRITTEN );\n    if ( writeField.getSubject() == null && mappingOutputs != null && mappingOutputs.length >= 1 ) {","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mapping/Mapping.java#L282-L318","documentation":"When the sub-transformation's type is SingleThreaded, the Mapping step creates a SingleThreadedTransExecutor and calls its init(). If any step inside the single-threaded sub-transformation fails to initialize, this exception is thrown so the whole mapping fails at init time rather than mid-execution.","triggerScenarios":"Mapping.init() -> prepareMappingExecution() with transformation type SingleThreaded, where singleThreadedTransExcecutor.init() returns false because one or more inner steps failed their init (bad connections, missing parameters, misconfigured steps).","commonSituations":"Using SingleThreaded transformation type for a mapping (often for bulk/parallel loading scenarios like with Hadoop/card output) where an inner step such as a table output cannot open its connection.","solutions":["Check the log lines just before this error for which step inside the mapping failed init and fix that step.","Verify database connections/credentials used by steps inside the single-threaded sub-transformation.","If single-threaded execution is not required, switch the sub-transformation type to Normal.","Ensure all required variables/parameters passed via the mapping's arguments are defined before execution."],"exampleFix":"null","handlingStrategy":"try-catch","validationCode":"// Ensure the single-threaded sub-transformation initializes before production use\nSingleThreadedTransExecutor ex = new SingleThreadedTransExecutor(new Trans(mappingTransMeta));\nif (!ex.init()) throw new IllegalStateException(\"Mapping inner steps failed init\");","typeGuard":null,"tryCatchPattern":"try {\n  mapping.init();\n} catch (KettleException e) {\n  if (String.valueOf(e.getMessage()).contains(\"single threaded\")) {\n    logError(\"A step inside the single-threaded mapping failed init — inspect preceding log lines\", e);\n  } else { throw e; }\n}","preventionTips":["Read the log immediately above this error to find the failing inner step.","Validate connections of every step in single-threaded mappings.","Only use SingleThreaded type when required (e.g. certain bulk loaders).","Pass all required variables/arguments before prepareExecution."],"tags":["pdi","kettle","mapping-step","single-threaded","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"}