pentaho/pentaho-kettle · error · KettleException

MappingDialog.Exception.StepNameNotFound

MappingDialog.Exception.StepNameNotFound

Error message

The step with name '{0}' couldn't be found.

What it means

The Mapping step lets you pin which parent-transformation step feeds each mapping input via an input step name. During prepareMappingExecution, if a configured input step name does not match any running step in the parent transformation (findRunThread returns null), this exception is thrown.

Solutions

  1. Open the Mapping step dialog and re-select the correct 'Input step' from the dropdown so it matches an existing step name.
  2. Rename the step in the parent transformation back to the name the mapping expects.
  3. Compare the Main input path configuration in the Mapping dialog with actual parent step names.
  4. If the mapping is built programmatically, ensure meta.getInputMappings() entries use step names that exist in the parent TransMeta.

Example fix

// before
mappingMeta.getInputMappings().get(0).setInputStepname("Old Step Name");
// after
mappingMeta.getInputMappings().get(0).setInputStepname("Sort rows 2");
Defensive patterns

Strategy: validation

Validate before calling

for (MappingIODefinition def : meta.getInputMappings()) {
  if (!Utils.isEmpty(def.getInputStepname())
      && transMeta.findStep(def.getInputStepname()) == null) {
    throw new IllegalStateException("Input step not found: " + def.getInputStepname());
  }
}

Try / catch

try {
  mapping.init();
} catch (KettleException e) {
  if (String.valueOf(e.getMessage()).startsWith("The step with name")) {
    logError("Mapping input step name no longer exists — fix Mapping dialog Input tab", e);
  } else { throw e; }
}

Prevention

When it happens

Trigger: Mapping metadata (MappingIODefinition.inputStepname) references a step name that does not exist, was renamed, or has not started (failed init) in the parent transformation when init() runs.

Common situations: Renaming or deleting a step in the parent transformation after configuring the mapping input; copy-pasting transformations between environments where step names differ; XML edits that desynchronize names.

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

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

Appendix: source

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

    // not receive ANY input and output rowsets.
    // This is an exception to the general rule, built into
    // Trans.prepareExecution()
    //
    // A Mapping Input step is supposed to read directly from the previous
    // steps.
    // A Mapping Output step is supposed to write directly to the next steps.

    // OK, check the input mapping definitions and look up the steps to read
    // from.
    //
    StepInterface[] sourceSteps;
    for ( MappingIODefinition inputDefinition : meta.getInputMappings() ) {
      // If we have a single step to read from, we use this
      //
      if ( !Utils.isEmpty( inputDefinition.getInputStepname() ) ) {
        StepInterface sourceStep = getTrans().findRunThread( inputDefinition.getInputStepname() );
        if ( sourceStep == null ) {
          throw new KettleException( BaseMessages.getString( PKG, "MappingDialog.Exception.StepNameNotFound",
              inputDefinition.getInputStepname() ) );
        }
        sourceSteps = new StepInterface[] { sourceStep, };
      } else {
        // We have no defined source step.
        // That means that we're reading from all input steps that this mapping
        // step has.
        //
        List<StepMeta> prevSteps = getTransMeta().findPreviousSteps( getStepMeta() );

        // TODO: Handle remote steps from: getStepMeta().getRemoteInputSteps()
        //

        // 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()];

View on GitHub (pinned to f3058517a1)