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

Thrown when no specific input step name is given and the sub-transformation contains more than one 'Mapping Input' step. Without an explicit step name Pentaho cannot decide which Mapping Input step's fields to use, so it rejects the ambiguity.

Solutions

1. Remove or disable the extra Mapping Input step so exactly one remains
2. Specify the input step name explicitly in the Mapping step dialog (Input Source tab) so the ambiguity disappears
3. Enable multi-input on the mapping definition and configure all input mappings explicitly

Example fix

// before: sub-transformation has two Mapping Input steps, no step specified
String inputStepName = null; // ambiguous
// after
String inputStepName = "Mapping Input 1"; // explicitly chosen in dialog

// before getFields
String[] inputs = MappingHelper.getMappingSteps(mappingTransMeta, true);
if (!Utils.isEmpty(inputStepName) == false && inputs.length > 1) {
  throw new IllegalStateException("Specify an input step: found " + inputs.length + " Mapping Input steps");
}

boolean unambiguousInput(String inputStepName, String[] mappingInputSteps) { return !Utils.isEmpty(inputStepName) || mappingInputSteps.length <= 1; }

try {
  fields = helper.getFieldsFromStep(...);
} catch (KettleException e) {
  logError("Ambiguous mapping input: " + e.getMessage());
  // reconfigure the mapping definition to name an input step
}

When it happens

Trigger: getFieldsFromMappingTrans with empty inputStepName and MappingHelper.getMappingSteps(...) returning length > 1 Mapping Input steps in the sub-transformation.

Common situations: Developer added a second Mapping Input step to a sub-transformation that the parent Mapping step references generically (input step left unspecified in the mapping definition).

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

• MappingDialog.Exception.NoMappingSpecified
• MappingDialog.Exception.OneMappingInputStepRequired
• MappingOutput.Exception.UnableToConnectWithParentMapping
• The simple mapping step does not support multiple Mapping…
• The simple mapping step needs one Mapping Input step to…

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingHelper.java:233

    } else {
      StepMeta stepMeta = transMeta.findStep( inputStepName );
      if ( stepMeta == null ) {
        throw new KettleException( BaseMessages.getString(
            PKG, "MappingDialog.Exception.SpecifiedStepWasNotFound", inputStepName ) );
      }
      return transMeta.getStepFields( stepMeta );
    }
  }

  private RowMetaInterface getFieldsFromMappingTrans( String inputStepName, TransMeta mappingTransMeta, boolean mappingInput ) throws KettleException {
    if ( mappingTransMeta == null ) {
      throw new KettleException( BaseMessages.getString( PKG, "MappingDialog.Exception.NoMappingSpecified" ) );
    }

    if ( Utils.isEmpty( inputStepName ) ) {
      String[] stepNames = MappingHelper.getMappingSteps( mappingTransMeta, mappingInput );
      if ( stepNames.length > 1 ) {
        throw new KettleException( BaseMessages.getString(
            PKG, "MappingDialog.Exception.OnlyOneMappingInputStepAllowed", "" + stepNames.length ) );
      }
      if ( stepNames.length == 0 ) {
        throw new KettleException( BaseMessages.getString(
            PKG, "MappingDialog.Exception.OneMappingInputStepRequired", "" + stepNames.length ) );
      }
      return mappingTransMeta.getStepFields( stepNames[ 0 ] );
    } else {
      StepMeta stepMeta = mappingTransMeta.findStep( inputStepName );
      if ( stepMeta == null ) {
        throw new KettleException( BaseMessages.getString(
            PKG, "MappingDialog.Exception.SpecifiedStepWasNotFound", inputStepName ) );
      }
      return mappingTransMeta.getStepFields( stepMeta );
    }
  }

  private JSONArray generateFieldsJSON( RowMetaInterface fields ) {

View on GitHub (pinned to f3058517a1)