pentaho/pentaho-kettle · error · KettleStepException

TransMeta.Exception.OnlyOneMappingInputStepAllowed

Error message

TransMeta.Exception.OnlyOneMappingInputStepAllowed

What it means

findMappingInputStep() with no step name scans the transformation for steps whose ID equals 'MappingInput'. If it finds more than one, it throws KettleStepException with TransMeta.Exception.OnlyOneMappingInputStepAllowed, because a mapping sub-transformation must have exactly one input step.

Solutions

  1. Remove the extra MappingInput step so exactly one remains
  2. Rename and configure the duplicate as a different step type if two inputs are genuinely needed
  3. Pass an explicit step name to findMappingInputStep to bypass auto-detection (only valid if your intent allows it)

Example fix

// before
// mapping.ktr contains MappingInput + copied MappingInput
StepMeta sm = transMeta.findMappingInputStep(null); // throws
// after
// keep one MappingInput step in the sub-transformation, then:
StepMeta sm = transMeta.findMappingInputStep(null);
Defensive patterns

Strategy: type-guard

Validate before calling

long count = Arrays.stream(transMeta.getStepsArray())
    .filter(s -> "MappingInput".equals(s.getStepID())).count();
if (count > 1) throw new IllegalStateException("Sub-transformation has " + count + " MappingInput steps; must have exactly 1");

Try / catch

try {
  StepMeta sm = transMeta.findMappingInputStep(null);
} catch (KettleStepException e) {
  logger.error("MappingInput count violation in {}: fix sub-transformation design", transMeta.getName());
  throw e;
}

Prevention

When it happens

Trigger: Calling findMappingInputStep(null/empty name) on a transformation containing two or more MappingInput steps.

Common situations: Copy-pasting a MappingInput step inside a mapping sub-transformation; merging transformations that each had their own MappingInput; template reuse without removing duplicates.

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/9b2e0e25537b4cbb. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/TransMeta.java:6126

   *           if any errors occur during the search
   */
  public StepMeta findMappingInputStep( String stepname ) throws KettleStepException {
    if ( !Utils.isEmpty( stepname ) ) {
      StepMeta stepMeta = findStep( stepname ); // TODO verify that it's a mapping input!!
      if ( stepMeta == null ) {
        throw new KettleStepException( BaseMessages.getString(
          PKG, "TransMeta.Exception.StepNameNotFound", stepname ) );
      }
      return stepMeta;
    } else {
      // Find the first mapping input step that fits the bill.
      StepMeta stepMeta = null;
      for ( StepMeta mappingStep : steps ) {
        if ( mappingStep.getStepID().equals( "MappingInput" ) ) {
          if ( stepMeta == null ) {
            stepMeta = mappingStep;
          } else if ( stepMeta != null ) {
            throw new KettleStepException( BaseMessages.getString(
              PKG, "TransMeta.Exception.OnlyOneMappingInputStepAllowed", "2" ) );
          }
        }
      }
      if ( stepMeta == null ) {
        throw new KettleStepException( BaseMessages.getString(
          PKG, "TransMeta.Exception.OneMappingInputStepRequired" ) );
      }
      return stepMeta;
    }
  }

  /**
   * Finds the mapping output step with the specified name. If no mapping output step is found, null is returned.
   *
   * @param stepname
   *          the name to search for
   * @return the step meta-data corresponding to the desired mapping input step, or null if no step was found

View on GitHub (pinned to f3058517a1)