pentaho/pentaho-kettle · error · KettleException

Mapping.Exception.UnableToInitSingleThreadedTransformation

Mapping.Exception.UnableToInitSingleThreadedTransformation

Error message

Unable to initialize the single threaded transformation engine because one or more steps failed to initialize.

What it means

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.

Solutions

  1. Check the log lines just before this error for which step inside the mapping failed init and fix that step.
  2. Verify database connections/credentials used by steps inside the single-threaded sub-transformation.
  3. If single-threaded execution is not required, switch the sub-transformation type to Normal.
  4. Ensure all required variables/parameters passed via the mapping's arguments are defined before execution.

Example fix

null
Defensive patterns

Strategy: try-catch

Validate before calling

// Ensure the single-threaded sub-transformation initializes before production use
SingleThreadedTransExecutor ex = new SingleThreadedTransExecutor(new Trans(mappingTransMeta));
if (!ex.init()) throw new IllegalStateException("Mapping inner steps failed init");

Try / catch

try {
  mapping.init();
} catch (KettleException e) {
  if (String.valueOf(e.getMessage()).contains("single threaded")) {
    logError("A step inside the single-threaded mapping failed init — inspect preceding log lines", e);
  } else { throw e; }
}

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/7c216d1da95742ce. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mapping/Mapping.java:300

    //
    try {
      mappingData.getMappingTrans().prepareExecution( getTrans().getArguments() );
    } catch ( KettleException e ) {
      throw new KettleException( BaseMessages.getString( PKG, "Mapping.Exception.UnableToPrepareExecutionOfMapping" ),
          e );
    }

    // Extra optional work to do for alternative execution engines...
    //
    switch (  mappingData.mappingTransMeta.getTransformationType() ) {
      case Normal:
      case SerialSingleThreaded:
        break;

      case SingleThreaded:
        mappingData.singleThreadedTransExcecutor = new SingleThreadedTransExecutor( mappingData.getMappingTrans() );
        if ( !mappingData.singleThreadedTransExcecutor.init() ) {
          throw new KettleException( BaseMessages.getString( PKG,
              "Mapping.Exception.UnableToInitSingleThreadedTransformation" ) );
        }
        break;
      default:
        break;
    }

    // If there is no read/write logging step set, we can insert the data from
    // the first mapping input/output step...
    //
    MappingInput[] mappingInputs = mappingData.getMappingTrans().findMappingInput();
    LogTableField readField = mappingData.mappingTransMeta.getTransLogTable().findField( TransLogTable.ID.LINES_READ );
    if ( readField.getSubject() == null && mappingInputs != null && mappingInputs.length >= 1 ) {
      readField.setSubject( mappingInputs[0].getStepMeta() );
    }
    MappingOutput[] mappingOutputs = mappingData.getMappingTrans().findMappingOutput();
    LogTableField writeField = mappingData.mappingTransMeta.getTransLogTable().findField( TransLogTable.ID.LINES_WRITTEN );
    if ( writeField.getSubject() == null && mappingOutputs != null && mappingOutputs.length >= 1 ) {

View on GitHub (pinned to f3058517a1)