pentaho/pentaho-kettle · error · KettleException

MappingDialog.Exception.SpecifiedStepWasNotFound

MappingDialog.Exception.SpecifiedStepWasNotFound

Error message

The Mapping source step name, '{0}', could not be found. Please specify a different name and try again.

What it means

Thrown by MappingHelper.getFieldsFromParentTrans when the input-step name configured on the Mapping (sub-transformation) step cannot be resolved via TransMeta.findStep() in the parent transformation. The library uses this lookup to determine which parent-transformation step supplies the field metadata; a null result means the configured name points to nothing.

Solutions

1. Open the Mapping step dialog and re-select a valid source step from the parent transformation
2. Check for typos or trailing whitespace in the configured input step name
3. Recreate the mapping definition after any step rename so the stored name updates
4. Diff the transformation XML (entry <input_step> or equivalent) against the actual step names

Example fix

// before (stale name in mapping definition)
String inputStepName = "Old Step Name"; // step was renamed
// after
String inputStepName = "Renamed Step Name"; // re-picked in Mapping dialog so it matches findStep()

// before using the Mapping step
if (transMeta.findStep(inputStepName) == null) {
  throw new IllegalArgumentException("Step '" + inputStepName + "' not found in parent transformation");
}

boolean stepExists(TransMeta tm, String name) { return name != null && tm.findStep(name) != null; }

try {
  RowMetaInterface fields = helper.getFieldsFromStep(...);
} catch (KettleException e) {
  logError("Mapping source step not found: " + e.getMessage());
  // surface a dialog/message telling the user to re-pick the step
}

When it happens

Trigger: getFieldsFromStep -> getFieldsFromParentTrans with a non-empty inputStepName that findStep() fails to match, i.e. the step name stored in the Mapping step's input/output mapping definition no longer exists in the parent transformation.

Common situations: The referenced step was renamed or deleted after configuring the Mapping step; the mapping definition was copied between transformations; metadata imported from another repository where the step name differs.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• BaseStep.Exception.SourceStepToReadFromDoesntExist
• BaseStep.Exception.TargetStepToWriteToDoesntExist
• MappingMeta.Exception.UnableToFindMappingDefinition
• MappingMeta.Exception.UnableToFindMetadataInfo
• AccessInput.Exception.CouldnotFindField

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

Appendix: source

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

  }

  public RowMetaInterface getFieldsFromStep( TransMeta transMeta, TransMeta mappingTransMeta, String stepName,
                                             String inputStepName, boolean getTransformationStep,
                                             boolean mappingInput ) throws KettleException {
    if ( mappingInput == getTransformationStep ) {
      return getFieldsFromParentTrans( inputStepName, transMeta, stepName );
    } else {
      return getFieldsFromMappingTrans( inputStepName, mappingTransMeta, mappingInput );
    }
  }

  private RowMetaInterface getFieldsFromParentTrans( String inputStepName, TransMeta transMeta, String stepName ) throws KettleException {
    if ( Utils.isEmpty( inputStepName ) ) {
      return transMeta.getPrevStepFields( stepName );
    } 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 ) {

View on GitHub (pinned to f3058517a1)