pentaho/pentaho-kettle · error · KettleException

The simple mapping step needs one Mapping Input step to…

Error message

The simple mapping step needs one Mapping Input step to write to in the sub-transformation

What it means

After preparing the mapping sub-transformation, SimpleMapping looks for the Mapping Input step(s) it should write data to. The simple mapping supports exactly one; if findMappingInput() returns zero, this KettleException is thrown because the parent step has no target inside the sub-transformation.

Solutions

Add exactly one 'Mapping Input' step to the sub-transformation and connect it to the rest of the flow
Confirm the referenced sub-transformation is actually a mapping (.ktr with Mapping Input/Output), not an ordinary transformation
Re-point the Simple Mapping step's sub-transformation setting to the correct mapping file

Example fix

// before (sub-transformation)
[Text Input] -> [Sort] -> [Mapping Output]
// after
[Mapping Input] -> [Sort] -> [Mapping Output]

Defensive patterns

Strategy: validation

Validate before calling

TransMeta sub = new TransMeta(mappingPath);
boolean hasMappingInput = sub.getSteps().stream().anyMatch(s -> "MappingInput".equals(s.getTypeId()));
if (!hasMappingInput) throw new IllegalArgumentException("mapping lacks Mapping Input step");

Try / catch

try { trans.execute(null); } catch (KettleException e) { if (e.getMessage().contains("needs one Mapping Input")) { /* repair sub-transformation then retry init */ } else throw e; }

Prevention

Always start a mapping sub-transformation with a Mapping Input step
Never point Simple Mapping at an ordinary transformation
Template new mappings from a known-good skeleton

When it happens

Trigger: prepareMappingExecution (from init) calls simpleMappingData.mappingTrans.findMappingInput() and gets an empty array — the sub-transformation contains no Mapping Input step.

Common situations: Building a mapping sub-transformation from scratch and forgetting the 'Mapping Input' step; deleting it during refactoring; pointing the Simple Mapping step at a normal .ktr instead of a mapping .ktr.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

    // 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 );

    // LogTableField readField = data.mappingTransMeta.getTransLogTable().findField(TransLogTable.ID.LINES_READ);
    // if (readField.getSubject() == null) {
    // readField.setSubject(data.mappingInput.getStepMeta());
    // }

    MappingOutput[] mappingOutputs = simpleMappingData.mappingTrans.findMappingOutput();
    if ( mappingOutputs.length == 0 ) {
      throw new KettleException(
          "The simple mapping step needs one Mapping Output step to read from in the sub-transformation" );

View on GitHub (pinned to f3058517a1)