pentaho/pentaho-kettle · error · KettleException

Unable to initialize the single threaded transformation…

Error message

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

What it means

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.

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

Example fix

// Sub-transformation's 'Table input' init fails: connection 'DW' undefined in the run configuration
// after: add the DW database connection to the job's run configuration / define it in the environment

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: verify the sub-transformation initializes standalone before wiring it into the SingleThreader
TransMeta sub = new TransMeta(mappingFile);
Trans t = new Trans(sub);
t.setVariable("...", value); // inject required variables
// run a dry verification in Spoon or via Trans.verify() before production

Try / catch

try {
  singleThreader.init(data); 
} catch (KettleException e) {
  logError("Sub-transformation steps failed to initialize: " + e.getMessage());
  return false;
}

Prevention

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

When it happens

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

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

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/singlethreader/SingleThreader.java:224

        // Simply pass it along to the next steps after the SingleThreader
        //
        SingleThreader.this.putRow( rowMeta, row );
      }
    } );

    singleThreaderData.mappingTrans.startThreads();

    // Create the executor...
    singleThreaderData.executor = new SingleThreadedTransExecutor( singleThreaderData.mappingTrans );

    // We launch the transformation in the processRow when the first row is received.
    // This will allow the correct variables to be passed.
    // Otherwise the parent is the init() thread which will be gone once the init is done.
    //
    try {
      boolean ok = singleThreaderData.executor.init();
      if ( !ok ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "SingleThreader.Exception.UnableToInitSingleThreadedTransformation" ) );
      }
    } catch ( KettleException e ) {
      throw new KettleException( BaseMessages.getString(
        PKG, "SingleThreader.Exception.UnableToPrepareExecutionOfMapping" ), e );
    }

    // Add the mapping transformation to the active sub-transformations map in the parent transformation
    //
    getTrans().addActiveSubTransformation( getStepname(), singleThreaderData.mappingTrans );
  }

  void initServletConfig() {
    TransStepUtil.initServletConfig( getTrans(), getData().getMappingTrans() );
  }

  public boolean init( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (SingleThreaderMeta) smi;

View on GitHub (pinned to f3058517a1)