{"record":{"id":"b6dbb4dd930af462","repo":"pentaho/pentaho-kettle","slug":"transmeta-exception-onemappinginputsteprequired","errorCode":null,"errorMessage":"TransMeta.Exception.OneMappingInputStepRequired","messagePattern":"TransMeta\\.Exception\\.OneMappingInputStepRequired","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/TransMeta.java","lineNumber":6132,"sourceCode":"        throw new KettleStepException( BaseMessages.getString(\n          PKG, \"TransMeta.Exception.StepNameNotFound\", stepname ) );\n      }\n      return stepMeta;\n    } else {\n      // Find the first mapping input step that fits the bill.\n      StepMeta stepMeta = null;\n      for ( StepMeta mappingStep : steps ) {\n        if ( mappingStep.getStepID().equals( \"MappingInput\" ) ) {\n          if ( stepMeta == null ) {\n            stepMeta = mappingStep;\n          } else if ( stepMeta != null ) {\n            throw new KettleStepException( BaseMessages.getString(\n              PKG, \"TransMeta.Exception.OnlyOneMappingInputStepAllowed\", \"2\" ) );\n          }\n        }\n      }\n      if ( stepMeta == null ) {\n        throw new KettleStepException( BaseMessages.getString(\n          PKG, \"TransMeta.Exception.OneMappingInputStepRequired\" ) );\n      }\n      return stepMeta;\n    }\n  }\n\n  /**\n   * Finds the mapping output step with the specified name. If no mapping output step is found, null is returned.\n   *\n   * @param stepname\n   *          the name to search for\n   * @return the step meta-data corresponding to the desired mapping input step, or null if no step was found\n   * @throws KettleStepException\n   *           if any errors occur during the search\n   */\n  public StepMeta findMappingOutputStep( String stepname ) throws KettleStepException {\n    if ( !Utils.isEmpty( stepname ) ) {\n      StepMeta stepMeta = findStep( stepname ); // TODO verify that it's a mapping output step.","sourceCodeStart":6114,"sourceCodeEnd":6150,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/TransMeta.java#L6114-L6150","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Add a 'Mapping input specification' step to the sub-transformation","Confirm you are operating on the intended mapping sub-transformation, not the parent","Verify the step's plugin ID is actually 'MappingInput' via getStepID()"],"exampleFix":"// before\nStepMeta sm = plainTransMeta.findMappingInputStep(null); // throws: no MappingInput\n// after\nif (Arrays.stream(transMeta.getStepIDs()).anyMatch(\"MappingInput\"::equals)) {\n  StepMeta sm = transMeta.findMappingInputStep(null);\n}","handlingStrategy":"type-guard","validationCode":"boolean hasInput = Arrays.stream(transMeta.getStepsArray())\n    .anyMatch(s -> \"MappingInput\".equals(s.getStepID()));\nif (!hasInput) throw new IllegalStateException(transMeta.getName() + \" is not a valid mapping sub-transformation (no MappingInput step)\");","typeGuard":null,"tryCatchPattern":"try {\n  StepMeta sm = mappingTransMeta.findMappingInputStep(null);\n} catch (KettleStepException e) {\n  logger.error(\"{} has no MappingInput step; add one before using it as a mapping\", mappingTransMeta.getName());\n  throw e;\n}","preventionTips":["Only load .ktr files designed as mapping sub-transformations via the Mapping step","Do not delete the MappingInput step during refactoring","Validate sub-transformation structure (1 MappingInput + 1 MappingOutput) before deployment"],"tags":["steps","mapping","design"],"backgroundTag":"entity-not-found","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}