{"record":{"id":"9b2e0e25537b4cbb","repo":"pentaho/pentaho-kettle","slug":"transmeta-exception-onlyonemappinginputstepallowed","errorCode":null,"errorMessage":"TransMeta.Exception.OnlyOneMappingInputStepAllowed","messagePattern":"TransMeta\\.Exception\\.OnlyOneMappingInputStepAllowed","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/TransMeta.java","lineNumber":6126,"sourceCode":"   *           if any errors occur during the search\n   */\n  public StepMeta findMappingInputStep( String stepname ) throws KettleStepException {\n    if ( !Utils.isEmpty( stepname ) ) {\n      StepMeta stepMeta = findStep( stepname ); // TODO verify that it's a mapping input!!\n      if ( stepMeta == null ) {\n        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","sourceCodeStart":6108,"sourceCodeEnd":6144,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/TransMeta.java#L6108-L6144","documentation":"findMappingInputStep() with no step name scans the transformation for steps whose ID equals 'MappingInput'. If it finds more than one, it throws KettleStepException with TransMeta.Exception.OnlyOneMappingInputStepAllowed, because a mapping sub-transformation must have exactly one input step.","triggerScenarios":"Calling findMappingInputStep(null/empty name) on a transformation containing two or more MappingInput steps.","commonSituations":"Copy-pasting a MappingInput step inside a mapping sub-transformation; merging transformations that each had their own MappingInput; template reuse without removing duplicates.","solutions":["Remove the extra MappingInput step so exactly one remains","Rename and configure the duplicate as a different step type if two inputs are genuinely needed","Pass an explicit step name to findMappingInputStep to bypass auto-detection (only valid if your intent allows it)"],"exampleFix":"// before\n// mapping.ktr contains MappingInput + copied MappingInput\nStepMeta sm = transMeta.findMappingInputStep(null); // throws\n// after\n// keep one MappingInput step in the sub-transformation, then:\nStepMeta sm = transMeta.findMappingInputStep(null);","handlingStrategy":"type-guard","validationCode":"long count = Arrays.stream(transMeta.getStepsArray())\n    .filter(s -> \"MappingInput\".equals(s.getStepID())).count();\nif (count > 1) throw new IllegalStateException(\"Sub-transformation has \" + count + \" MappingInput steps; must have exactly 1\");","typeGuard":null,"tryCatchPattern":"try {\n  StepMeta sm = transMeta.findMappingInputStep(null);\n} catch (KettleStepException e) {\n  logger.error(\"MappingInput count violation in {}: fix sub-transformation design\", transMeta.getName());\n  throw e;\n}","preventionTips":["Design mapping sub-transformations with exactly one MappingInput step","After copy/paste or merge operations in Spoon, verify step plugin IDs","Add a design-time lint that counts MappingInput/MappingOutput steps per mapping"],"tags":["steps","mapping","design"],"backgroundTag":"conflicting-config-options","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"}