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 Output steps to read from in the sub-transformation

What it means

Simple Mapping supports exactly one Mapping Output step in its sub-transformation: the single place from which processed rows are read back into the parent. When prepareMappingExecution (called from init) finds more than one Mapping Output step via findMappingOutput(), the mapping contract is ambiguous, so a KettleException is thrown.

Solutions

  1. Open the sub-transformation and delete all but one Mapping Output step (or replace extras with normal steps that don't act as mapping outputs).
  2. Split the logic into separate Simple Mapping steps, each pointing at a sub-transformation with a single Mapping Output.
  3. If multiple outputs are genuinely needed, consider using a Mapping (simple) alternative or restructuring with a single Mapping Output that branches downstream in the parent transformation.

Example fix

// Sub-transformation had two terminal steps:
//   ... -> Mapping output
//   ... -> Mapping output
// Fix: keep exactly one
//   ... -> Mapping output
// and route the second branch into the same Mapping output (or drop it)
Defensive patterns

Strategy: validation

Validate before calling

// Guard before executing: exactly one Mapping Output allowed
MappingOutput[] outputs = mappingTrans.findMappingOutput();
if (outputs != null && outputs.length > 1) {
  throw new IllegalStateException("Mapping sub-transformation has " + outputs.length + " Mapping Output steps; only one is supported");
}

Try / catch

try {
  simpleMapping.init(data); 
} catch (KettleException e) {
  logError("Invalid mapping structure: " + e.getMessage());
  return false;
}

Prevention

When it happens

Trigger: SimpleMapping.prepareMappingExecution() calls simpleMappingData.mappingTrans.findMappingOutput(), which returns length > 1 because the sub-transformation contains two or more Mapping Output steps.

Common situations: A sub-transformation was copied/duplicated leaving two Mapping Output steps; a developer tried to fan out multiple output branches each with its own Mapping Output step (use Multi-Way / multiple Simple Mapping steps instead); merging two mappings into one sub-transformation.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

    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" );
    }
    simpleMappingData.mappingOutput = mappingOutputs[0];

    // LogTableField writeField = data.mappingTransMeta.getTransLogTable().findField(TransLogTable.ID.LINES_WRITTEN);
    // if (writeField.getSubject() == null && data.mappingOutputs != null && data.mappingOutputs.length >= 1) {
    // writeField.setSubject(data.mappingOutputs[0].getStepMeta());
    // }

    // Finally, add the mapping transformation to the active sub-transformations
    // map in the parent transformation
    //
    getTrans().addActiveSubTransformation( getStepname(), simpleMappingData.mappingTrans );
  }

  void initServletConfig() {
    TransStepUtil.initServletConfig( getTrans(), getData().getMappingTrans() );
  }

View on GitHub (pinned to f3058517a1)