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

The Simple Mapping step hosts a sub-transformation (mapping). prepareMappingExecution calls mappingTrans.prepareExecution(...) to allocate and initialize the sub-transformation's steps; if the sub-transformation fails to initialize (KettleException), it is re-wrapped as this error so the cause must be inspected in the chained exception.

Solutions

Read the nested cause exception in the stack trace — it names the failing sub-step
Open the mapping .ktr and fix/validate the failing step inside it
Reconnect Mapping Input/Mapping Output steps after renames
Ensure all required step plugins used by the sub-transformation are installed
Verify the sub-transformation file path/repository location is correct

Example fix

// before
mappingPath = "/jobs/mapping_v1.ktr"; // file missing
// after
mappingPath = "/jobs/mapping_v2.ktr";

Defensive patterns

Strategy: try-catch

Validate before calling

TransMeta subMeta = new TransMeta(mappingPath);
// pre-load and check the sub-transformation exists and its steps resolve
if (subMeta.getSteps().isEmpty()) throw new IllegalArgumentException("empty mapping");

Try / catch

try { trans.execute(null); } catch (KettleException e) { if (e.getMessage().contains("Unable to prepare") ) { log("Mapping init failed: ", e.getCause()); /* inspect cause for failing sub-step */ } else throw e; }

Prevention

Install all plugins used by the sub-transformation
Validate the mapping .ktr opens cleanly in Spoon before wiring it
Keep mapping files with their parent jobs in the same repo/path

When it happens

Trigger: init() -> prepareMappingExecution -> mappingTrans.prepareExecution throws because a step inside the mapping's .ktr cannot initialize (missing step plugin, bad field mappings, sub-step metadata errors).

Common situations: Mapping sub-transformation references steps from plugins not installed; Mapping Input/Output removed or renamed so connectors are broken; wrong arguments or parameter mapping; sub-transformation file moved.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMapping.java:171

    simpleMappingData.mappingTrans.setGatheringMetrics( getTrans().isGatheringMetrics() );

    // Also set the name of this step in the mapping transformation for logging
    // purposes
    //
    simpleMappingData.mappingTrans.setMappingStepName( getStepname() );

    initServletConfig();

    // 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 {
      simpleMappingData.mappingTrans.prepareExecution( getTrans().getArguments() );
    } catch ( KettleException e ) {
      throw new KettleException( BaseMessages.getString( PKG,
          "SimpleMapping.Exception.UnableToPrepareExecutionOfMapping" ), e );
    }

    // If there is no read/write logging step set, we can insert the data from
    // the first mapping input/output step...
    //
    MappingInput[] mappingInputs = simpleMappingData.mappingTrans.findMappingInput();
    if ( mappingInputs.length == 0 ) {
      throw new KettleException(
        "The simple mapping step needs one Mapping Input step to write to in the sub-transformation" );
    }
    if ( mappingInputs.length > 1 ) {
      throw new KettleException(
        "The simple mapping step does not support multiple Mapping Input steps to write to in the sub-transformation" );
    }
    simpleMappingData.mappingInput = mappingInputs[0];
    simpleMappingData.mappingInput.setConnectorSteps( new StepInterface[0], new ArrayList<MappingValueRename>(), null );

View on GitHub (pinned to f3058517a1)