pentaho/pentaho-kettle · error · KettleException

Mapping.Exception.UnableToPrepareExecutionOfMapping

Mapping.Exception.UnableToPrepareExecutionOfMapping

Error message

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

What it means

During Mapping.init(), the parent step allocates and initializes the sub-transformation via Trans.prepareExecution(). If that inner call throws any KettleException (e.g. a step in the mapping failed to initialize), it is re-wrapped with this message so the root cause from the sub-transformation is preserved as the cause.

Solutions

Read the wrapped 'cause' exception in the stack trace — it names the actual failing step or resource inside the mapping and fix that first.
Open the sub-transformation and verify every step initializes (run it standalone).
Check database connections and environment variables/parameters used inside the mapping.
Verify the mapping transformation file path (or repository entry) resolves at runtime and the mapping runs on its own.

Example fix

null

Defensive patterns

Strategy: try-catch

Validate before calling

// Before run: execute the sub-transformation standalone to verify init succeeds
Trans test = new Trans(mappingTransMeta);
test.prepareExecution(args); // throws early with the real root cause

Try / catch

try {
  mapping.init();
} catch (KettleException e) {
  Throwable root = e;
  while (root.getCause() != null) root = root.getCause();
  logError("Mapping prepareExecution failed: " + root.getMessage(), root);
}

Prevention

Test sub-transformations standalone before wiring them as mappings.
Verify all DB connections and variables used inside the mapping resolve in the target environment.
Keep all step plugin jars installed on every node.
Check the 'cause' chain — the true failure is always wrapped inside.

When it happens

Trigger: Mapping.init() -> prepareMappingExecution() -> mappingTrans.prepareExecution(...) throwing, e.g. because a step inside the sub-transformation failed init(), a database connection in the mapping is unavailable, or the sub-transformation metadata is invalid.

Common situations: Broken DB connections inside the sub-transformation; missing plugin step types in the mapping; invalid variable references; the referenced mapping transformation file missing or failing to load at runtime.

Related errors

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

Appendix: source

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

      //
      throw new KettleException( t );
    }
  }


  public void prepareMappingExecution() throws KettleException {
    initTransFromMeta();
    MappingData mappingData = getData();
    // 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 {
      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:

View on GitHub (pinned to f3058517a1)