pentaho/pentaho-kettle · error · KettleStepException

TransMeta.Exception.StepNameNotFound

Error message

TransMeta.Exception.StepNameNotFound

What it means

findMappingInputStep(String stepname) looks up a step by name when a name is provided. If findStep returns null (no step with that name exists in the transformation), it throws KettleStepException with TransMeta.Exception.StepNameNotFound. It is used to wire mapping input steps in sub-transformations.

Solutions

1. Print/list all step names (getStepNames()) and use the exact name, matching case and whitespace
2. If the name may be absent, guard with findStep(stepname) != null before calling
3. Pass null/empty to let the method auto-detect the first MappingInput step instead of a literal name

Example fix

// before
StepMeta sm = transMeta.findMappingInputStep("Inpt Step"); // throws
// after
StepMeta sm = transMeta.findStep("Input Step") != null
  ? transMeta.findMappingInputStep("Input Step")
  : transMeta.findMappingInputStep(null); // auto-detect

if (Arrays.asList(transMeta.getStepNames()).contains(expectedName)) {
  StepMeta sm = transMeta.findMappingInputStep(expectedName);
}

StepMeta guard = transMeta.findStep(name);
if (guard == null) throw new IllegalArgumentException("No step named '" + name + "' in " + transMeta.getName());

try {
  StepMeta sm = transMeta.findMappingInputStep(stepname);
} catch (KettleStepException e) {
  logger.error("Step '{}' not found. Available: {}", stepname, Arrays.toString(transMeta.getStepNames()));
  throw e;
}

When it happens

Trigger: Calling findMappingInputStep with a step name that does not exist in this transformation (typo, renamed step, wrong transformation object, name containing unexpected whitespace/case differences).

Common situations: Hard-coded step names broken after renaming in Spoon; parameterizing step names from config that drifted; searching the wrong TransMeta (parent vs mapping sub-transformation).

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• TransMeta.Exception.OneMappingInputStepRequired
• TransMeta.Exception.OnlyOneMappingInputStepAllowed
• TransMeta.Exception.OnlyOneMappingOutputStepAllowed
• Could not find field
• database type with plugin id [] couldn't be found!

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

Appendix: source

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

        : filename != null ? Const.INTERNAL_VARIABLE_TRANSFORMATION_FILENAME_DIRECTORY
        : Const.INTERNAL_VARIABLE_ENTRY_CURRENT_DIRECTORY ) );
  }


  /**
   * Finds the mapping input step with the specified name. If no mapping input 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 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(

View on GitHub (pinned to f3058517a1)