pentaho/pentaho-kettle · error · KettleException

MappingDialog.Exception.OneMappingInputStepRequired

MappingDialog.Exception.OneMappingInputStepRequired

Error message

The specified mapping needs a single 'mapping input' step to work with, but we couldn't find one.

What it means

When no explicit target/output step name is given for a mapping input definition, the Mapping step expects the sub-transformation to contain exactly one 'Mapping Input' step. If findMappingInput() returns zero such steps, this exception is thrown because there is nothing to feed rows into.

Solutions

Open the sub-transformation and add a 'Mapping Input' step.
Verify the Mapping step points at the intended sub-transformation that contains a Mapping Input step.
If the sub-transformation legitimately has multiple mapping inputs, specify the target step name explicitly in the Mapping dialog's input mapping table.
Re-export/clone the mapping from a known-good template that includes Mapping Input/Output steps.

Example fix

null

Defensive patterns

Strategy: validation

Validate before calling

MappingMeta mm = (MappingMeta) stepMeta.getStepMetaInterface();
boolean noTarget = mm.getInputMappings().stream()
    .allMatch(d -> Utils.isEmpty(d.getOutputStepname()));
if (noTarget && mappingTransMeta.findMappingInputSteps().isEmpty()) {
  throw new IllegalStateException("Sub-transformation has no 'Mapping Input' step");
}

Try / catch

try {
  mapping.init();
} catch (KettleException e) {
  if (String.valueOf(e.getMessage()).contains("'mapping input' step")) {
    logError("Add a 'Mapping Input' step to the sub-transformation", e);
  } else { throw e; }
}

Prevention

Always include exactly one 'Mapping Input' step in any transformation used as a mapping.
Verify the sub-transformation referenced in the Mapping dialog is the intended file.
Use PDI's mapping template when creating new sub-transformations.
Validate ktr contents after import/export operations.

When it happens

Trigger: prepareMappingExecution() handling an input definition with empty outputStepname, while the sub-transformation contains no Mapping Input step at all (mappingInputSteps.length == 0).

Common situations: Building a sub-transformation and forgetting to add a 'Mapping Input' step; using a transformation as a mapping that was designed as a standalone transformation; wrong transformation selected in the Mapping step dialog.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

        // Let's read data from all the previous steps we find...
        // The origin is the previous step
        // The target is the Mapping Input step.
        //
        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",

View on GitHub (pinned to f3058517a1)