pentaho/pentaho-kettle · error · KettleException

The simple mapping step does not support multiple Mapping…

Error message

The simple mapping step does not support multiple Mapping Input steps to write to in the sub-transformation

What it means

SimpleMapping supports exactly one Mapping Input step in the sub-transformation. If findMappingInput() returns more than one, this KettleException is thrown because the parent step cannot decide where to write incoming rows.

Solutions

Remove extra Mapping Input steps so exactly one remains in the sub-transformation
If multiple inputs are needed, switch to the full 'Mapping' step which supports multiple input streams
Branch after the single Mapping Input instead of duplicating it

Example fix

// before (sub-transformation)
[Mapping Input A] -> ... ; [Mapping Input B] -> ...
// after
[Mapping Input] -> ... ; [Mapping Input] removed

Defensive patterns

Strategy: validation

Validate before calling

TransMeta sub = new TransMeta(mappingPath);
long count = sub.getSteps().stream().filter(s -> "MappingInput".equals(s.getTypeId())).count();
if (count > 1) throw new IllegalArgumentException("simple mapping allows only one Mapping Input, found " + count);

Try / catch

try { trans.execute(null); } catch (KettleException e) { if (e.getMessage().contains("does not support multiple Mapping Input")) { /* switch to full Mapping step or deduplicate */ } else throw e; }

Prevention

Keep exactly one Mapping Input per simple mapping
Use the full Mapping step when multiple inputs are required
Review duplicated steps after copy-paste edits in mappings

When it happens

Trigger: prepareMappingExecution (from init) finds 2+ Mapping Input steps in the sub-transformation referenced by the Simple Mapping step.

Common situations: Copy-pasting the Mapping Input step inside a mapping to branch data; merging mappings that each had their own Mapping Input; using the full 'Mapping' step behavior expectations in a 'Simple Mapping' step.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

    // 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" );
    }
    if ( mappingOutputs.length > 1 ) {
      throw new KettleException( "The simple mapping step does not support "
          + "multiple Mapping Output steps to read from in the sub-transformation" );

View on GitHub (pinned to f3058517a1)