pentaho/pentaho-kettle · error · KettleException

MappingDialog.Exception.OnlyOneMappingInputStepAllowed

MappingDialog.Exception.OnlyOneMappingInputStepAllowed

Error message

Without specifying specific stepnames to read from, there can only be one 'mapping input' step in the mapping and we found {0}.

What it means

When no target step name is specified for a mapping input, the sub-transformation must contain exactly one 'Mapping Input' step. If findMappingInput() finds more than one, the step cannot decide which to wire up, so it throws this error reporting the number found (message contains typo 'specifif' in this codebase).

Solutions

Remove the extra 'Mapping Input' steps so the sub-transformation has exactly one.
Or explicitly select which Mapping Input step to use in the Mapping step dialog (Input tab, target step column).
Rename and restructure the sub-transformation to route all inputs through a single Mapping Input step.
Audit the .ktr for duplicate MappingInput step types if the UI count disagrees with expectations.

Example fix

null

Defensive patterns

Strategy: validation

Validate before calling

if (Utils.isEmpty(inputDefinition.getOutputStepname())) {
  long n = mappingTransMeta.getSteps().stream()
      .filter(s -> s.getStepMetaInterface() instanceof MappingInput).count();
  if (n != 1) throw new IllegalStateException("Expected 1 Mapping Input step, found " + n);
}

Try / catch

try {
  mapping.init();
} catch (KettleException e) {
  if (String.valueOf(e.getMessage()).contains("only be one 'mapping input'")) {
    logError("Multiple Mapping Input steps found — remove extras or pick a target explicitly", e);
  } else { throw e; }
}

Prevention

Never duplicate the 'Mapping Input' step when copying flows.
If multiple inputs are needed, wire them through one Mapping Input or specify targets explicitly.
Review sub-transformations after merges/refactors for duplicate input steps.
Count MappingInput occurrences in the ktr XML during CI checks.

When it happens

Trigger: prepareMappingExecution() with inputDefinition.getOutputStepname() empty and mappingInputSteps.length > 1 — i.e. sub-transformation has two or more Mapping Input steps while the Mapping dialog has no target step chosen.

Common situations: Copying an existing Mapping Input step inside the sub-transformation; merging transformations that each had their own Mapping Input; ambiguous legacy mappings after refactor.

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/238b0938266a2fcc. Report an issue: GitHub.

Appendix: source

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

        sourceSteps = new StepInterface[prevSteps.size()];
        for ( int s = 0; s < sourceSteps.length; s++ ) {
          sourceSteps[s] = getTrans().findRunThread( prevSteps.get( s ).getName() );
        }
      }

      // What step are we writing to?
      MappingInput mappingInputTarget = null;
      MappingInput[] mappingInputSteps = mappingData.getMappingTrans().findMappingInput();
      if ( Utils.isEmpty( inputDefinition.getOutputStepname() ) ) {
        // No target was specifically specified.
        // That means we only expect one "mapping input" step in the mapping...

        if ( mappingInputSteps.length == 0 ) {
          throw new KettleException( BaseMessages
              .getString( PKG, "MappingDialog.Exception.OneMappingInputStepRequired" ) );
        }
        if ( mappingInputSteps.length > 1 ) {
          throw new KettleException( BaseMessages.getString( PKG,
              "MappingDialog.Exception.OnlyOneMappingInputStepAllowed", "" + mappingInputSteps.length ) );
        }

        mappingInputTarget = mappingInputSteps[0];
      } else {
        // A target step was specified. See if we can find it...
        for ( int s = 0; s < mappingInputSteps.length && mappingInputTarget == null; s++ ) {
          if ( mappingInputSteps[s].getStepname().equals( inputDefinition.getOutputStepname() ) ) {
            mappingInputTarget = mappingInputSteps[s];
          }
        }
        // If we still didn't find it it's a drag.
        if ( mappingInputTarget == null ) {
          throw new KettleException( BaseMessages.getString( PKG, "MappingDialog.Exception.StepNameNotFound",
              inputDefinition.getOutputStepname() ) );
        }
      }

View on GitHub (pinned to f3058517a1)