{"record":{"id":"2c35c1caf5a7403a","repo":"pentaho/pentaho-kettle","slug":"transmeta-exception-onlyonemappingoutputstepallowed","errorCode":null,"errorMessage":"TransMeta.Exception.OnlyOneMappingOutputStepAllowed","messagePattern":"TransMeta\\.Exception\\.OnlyOneMappingOutputStepAllowed","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/TransMeta.java","lineNumber":6164,"sourceCode":"   *           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.\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 output step that fits the bill.\n      StepMeta stepMeta = null;\n      for ( StepMeta mappingStep : steps ) {\n        if ( mappingStep.getStepID().equals( \"MappingOutput\" ) ) {\n          if ( stepMeta == null ) {\n            stepMeta = mappingStep;\n          } else if ( stepMeta != null ) {\n            throw new KettleStepException( BaseMessages.getString(\n              PKG, \"TransMeta.Exception.OnlyOneMappingOutputStepAllowed\", \"2\" ) );\n          }\n        }\n      }\n      if ( stepMeta == null ) {\n        throw new KettleStepException( BaseMessages.getString(\n          PKG, \"TransMeta.Exception.OneMappingOutputStepRequired\" ) );\n      }\n      return stepMeta;\n    }\n  }\n\n  /**\n   * Gets a list of the resource dependencies.\n   *\n   * @return a list of ResourceReferences\n   */\n  public List<ResourceReference> getResourceDependencies() {","sourceCodeStart":6146,"sourceCodeEnd":6182,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/TransMeta.java#L6146-L6182","documentation":"findMappingOutputStep() with no step name scans for steps whose ID equals 'MappingOutput'. If two or more are present, it throws KettleStepException with TransMeta.Exception.OnlyOneMappingOutputStepAllowed, since a mapping sub-transformation must have exactly one output step.","triggerScenarios":"Calling findMappingOutputStep(null/empty name) on a transformation containing multiple MappingOutput steps.","commonSituations":"Duplicated MappingOutput step from copy/paste in a mapping sub-transformation; merging two mappings into one file; template copies not cleaned up.","solutions":["Delete the redundant MappingOutput step(s), leaving exactly one","Split into separate mapping sub-transformations if multiple outputs are truly required","Reference the desired output step explicitly by name instead of auto-detection"],"exampleFix":"// before\n// mapping.ktr has two MappingOutput steps\nStepMeta sm = transMeta.findMappingOutputStep(null); // throws\n// after\n// remove the duplicate MappingOutput in Spoon, then:\nStepMeta sm = transMeta.findMappingOutputStep(null);","handlingStrategy":"type-guard","validationCode":"long count = Arrays.stream(transMeta.getStepsArray())\n    .filter(s -> \"MappingOutput\".equals(s.getStepID())).count();\nif (count > 1) throw new IllegalStateException(\"Sub-transformation has \" + count + \" MappingOutput steps; must have exactly 1\");","typeGuard":null,"tryCatchPattern":"try {\n  StepMeta sm = transMeta.findMappingOutputStep(null);\n} catch (KettleStepException e) {\n  logger.error(\"MappingOutput count violation in {}: remove duplicate MappingOutput steps\", transMeta.getName());\n  throw e;\n}","preventionTips":["Design mapping sub-transformations with exactly one MappingOutput step","Clean up duplicated steps after copy/paste or merging transformations","Lint mapping files for exactly one MappingInput and one MappingOutput at build time"],"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"}