pentaho/pentaho-kettle · error · KettleException

Unable to prepare (allocate, initialize) the execution of…

Error message

Unable to prepare (allocate, initialize) the execution of the mapping (sub-transformation)

What it means

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.

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.

Example fix

// Stack trace:
// Unable to prepare (allocate, initialize) the execution of the mapping (sub-transformation)
//   Caused by: Unable to initialize the single threaded transformation engine...
//     Caused by: DB connection 'DW' init failed
// after: configure 'DW' connection correctly, then re-run

Defensive patterns

Strategy: try-catch

Try / catch

try {
  singleThreader.init(data);
} catch (KettleException e) {
  // This message is a wrapper: log and surface the root cause
  Throwable root = e;
  while (root.getCause() != null) root = root.getCause();
  logError("SingleThreader preparation failed, root cause: " + root.getMessage(), e);
  return false;
}

Prevention

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

When it happens

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

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

Related errors

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

Appendix: source

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

    } );

    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;
    setData( (SingleThreaderData) sdi );
    SingleThreaderData singleThreaderData = getData();
    if ( super.init( smi, sdi ) ) {
      // First we need to load the mapping (transformation)

View on GitHub (pinned to f3058517a1)