pentaho/pentaho-kettle · error · KettleException

Unsupported situation detected where more than one Mapping…

Error message

Unsupported situation detected where more than one Mapping Input step needs to be handled.  To solve it, insert a dummy step before the mapping step.

What it means

In Mapping.processRow, while wiring up input row sets, the code can only attach a row set to mappingInputs[0]. If a second Mapping Input step exists in the sub-transformation, there is no defined place for the row set, so a KettleException is thrown. The Mapping step supports only one unambiguous mapping input unless a dummy step disambiguates the hop.

Solutions

Insert a Dummy step between the parent step and the Mapping step in the parent transformation, as the message says.
Alternatively, ensure the sub-transformation has exactly one Mapping Input step; remove or merge extra ones.
If multiple inputs are truly needed, redesign so each Mapping Input is fed by a separate, explicitly wired mapping usage or use 'Mapping (sub-transformation)' executor with proper input specification.
Check the 'Mapping Input step' selection in the Mapping step dialog matches the intended sub-step name.

Example fix

// before (parent transformation)
TableInput -----> Mapping(sub.ktr)   // sub.ktr has MappingInput1 and MappingInput2
// after
TableInput -----> Dummy -----> Mapping(sub.ktr)  // disambiguates hop wiring

Defensive patterns

Strategy: validation

Validate before calling

// Inspect the sub-transformation before wiring:
long inputs = subTransMeta.getSteps().stream()
  .filter(s -> "MappingInput".equals(s.getStepMeta().getTypeDescription().replace(" ", "")))
  .count();
if (inputs > 1) throw new IllegalStateException("Sub-transformation has " + inputs + " Mapping Input steps; add a Dummy or reduce to 1");

Try / catch

try {
  trans.execute(null);
} catch (KettleException e) {
  if (e.getMessage().contains("more than one Mapping Input")) {
    log.error("Ambiguous mapping input wiring: insert a Dummy step before the Mapping step", e);
  } else { throw e; }
}

Prevention

Keep one Mapping Input step per reusable sub-transformation.
Insert a Dummy step whenever parent wiring is ambiguous.
Review sub-transf topology after refactoring/merging transformations.
Test mappings locally before deploying to shared environments.

When it happens

Trigger: A parent transformation feeds a Mapping (sub-transformation) step whose sub-transformation contains more than one 'Mapping Input' step, and the incoming row set cannot be matched to a single Mapping Input — detected while iterating input row sets in processRow (Mapping type Standard).

Common situations: Reusing a sub-transformation that has multiple Mapping Inputs with a plain Mapping step; adding a second Mapping Input while editing the sub-transf and forgetting the parent wiring; copying sub-transfs between transformations.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

          // Before we start, let's see if there are loose ends to tie up...
          //
          List<RowSet> inputRowSets = getInputRowSets();
          if ( !inputRowSets.isEmpty() ) {
            for ( RowSet rowSet : inputRowSets ) {
              // Pass this rowset down to a mapping input step in the
              // sub-transformation...
              //
              if ( mappingInputs.length == 1 ) {
                // Simple case: only one input mapping. Move the RowSet over
                //
                mappingInputs[0].addRowSetToInputRowSets( rowSet );
              } else {
                // Difficult to see what's going on here.
                // TODO: figure out where this RowSet needs to go and where it
                // comes from.
                //
                throw new KettleException(
                    "Unsupported situation detected where more than one Mapping Input step needs to be handled.  "
                        + "To solve it, insert a dummy step before the mapping step." );
              }
            }
            clearInputRowSets();
          }

          // Do the same thing for remote input steps...
          //
          if ( !getRemoteInputSteps().isEmpty() ) {
            // The remote server is likely a master or a slave server sending data
            // over remotely to this mapping.
            // However, the data needs to end up at a Mapping Input step of the
            // sub-transformation, not in this step.
            // We can move over the remote steps to the Mapping Input step as long
            // as the threads haven't started yet.
            //
            for ( RemoteStep remoteStep : getRemoteInputSteps() ) {

View on GitHub (pinned to f3058517a1)