pentaho/pentaho-kettle · error · KettleStepException

TransMeta.Exception.OneMappingInputStepRequired

Error message

TransMeta.Exception.OneMappingInputStepRequired

What it means

findMappingInputStep() with no step name requires the transformation to contain at least one MappingInput step. When none exists, it throws KettleStepException with TransMeta.Exception.OneMappingInputStepRequired. A valid mapping sub-transformation must contain exactly one MappingInput step.

Solutions

1. Add a 'Mapping input specification' step to the sub-transformation
2. Confirm you are operating on the intended mapping sub-transformation, not the parent
3. Verify the step's plugin ID is actually 'MappingInput' via getStepID()

Example fix

// before
StepMeta sm = plainTransMeta.findMappingInputStep(null); // throws: no MappingInput
// after
if (Arrays.stream(transMeta.getStepIDs()).anyMatch("MappingInput"::equals)) {
  StepMeta sm = transMeta.findMappingInputStep(null);
}

boolean hasInput = Arrays.stream(transMeta.getStepsArray())
    .anyMatch(s -> "MappingInput".equals(s.getStepID()));
if (!hasInput) throw new IllegalStateException(transMeta.getName() + " is not a valid mapping sub-transformation (no MappingInput step)");

try {
  StepMeta sm = mappingTransMeta.findMappingInputStep(null);
} catch (KettleStepException e) {
  logger.error("{} has no MappingInput step; add one before using it as a mapping", mappingTransMeta.getName());
  throw e;
}

When it happens

Trigger: Calling findMappingInputStep(null/empty name) on a transformation that has zero MappingInput steps (a regular transformation, or the MappingInput step was deleted/renamed to another type).

Common situations: Loading a normal .ktr as a mapping sub-transformation; deleting the MappingInput during refactoring; using the wrong step plugin (e.g. a Generic step standing in for MappingInput).

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• TransMeta.Exception.OnlyOneMappingInputStepAllowed
• TransMeta.Exception.OnlyOneMappingOutputStepAllowed
• TransMeta.Exception.StepNameNotFound
• Could not find field
• Field [ ] couldn't be found in the input stream!

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

Appendix: source

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

        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
   * @throws KettleStepException
   *           if any errors occur during the search
   */
  public StepMeta findMappingOutputStep( String stepname ) throws KettleStepException {
    if ( !Utils.isEmpty( stepname ) ) {
      StepMeta stepMeta = findStep( stepname ); // TODO verify that it's a mapping output step.

View on GitHub (pinned to f3058517a1)