{"record":{"id":"d7ee5f6d86e269e4","repo":"pentaho/pentaho-kettle","slug":"transmeta-exception-onemappingoutputsteprequired","errorCode":null,"errorMessage":"TransMeta.Exception.OneMappingOutputStepRequired","messagePattern":"TransMeta\\.Exception\\.OneMappingOutputStepRequired","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/TransMeta.java","lineNumber":6170,"sourceCode":"        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() {\n    return steps.stream()\n      .flatMap( (StepMeta stepMeta) -> stepMeta.getResourceDependencies( this ).stream() )\n      .collect( Collectors.toList() );\n  }\n\n  /**","sourceCodeStart":6152,"sourceCodeEnd":6188,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/TransMeta.java#L6152-L6188","documentation":"TransMeta.findMappingOutputStep() requires the transformation metadata to contain exactly one step of type MappingOutput; it throws KettleStepException with the 'OneMappingOutputStepRequired' key when no such step exists. Mapping (sub-)transformations need a MappingOutput step to feed results back to the parent transformation.","triggerScenarios":"Calling TransMeta.findMappingOutputStep() (via mapping step execution, e.g. when a parent transformation runs a Mapping step) on a TransMeta whose step list contains zero MappingOutput steps.","commonSituations":"A user builds or loads a mapping transformation and forgets to add a 'Mapping Output' step; a mapping XML/S repository export was edited or truncated and the MappingOutput step was lost; programmatically assembling a sub-transformation for the Mapping step type without adding the output step.","solutions":["Open the sub-transformation used as the mapping and add a 'Mapping Output' step connected to the transformation's output flow.","Verify the mappingFileName/transformation reference in the parent's Mapping step points to the intended sub-transformation, not the parent itself.","If building TransMeta in code, add a StepMeta whose plugin/step is org.pentaho.di.trans.steps.mappingoutput.MappingOutput and addStep it before running.","Re-export or re-import the mapping from the repository if the saved XML lost the step."],"exampleFix":"// before: sub-transformation has only Text File Input -> (nothing)\n// after: connect Text File Input -> Mapping Output step in the mapping transformation\n// code equivalent:\n// StepMeta mappingOutput = new StepMeta(\"MappingOutput\",\n//   new MappingOutputMeta());\n// mappingOutput.setLocation(100, 100);\n// transMeta.addStep(mappingOutput);\n// transMeta.addTransHop(new TransHopMeta(textInput, mappingOutput));","handlingStrategy":"validation","validationCode":"boolean ok = transMeta.getSteps().stream()\n  .anyMatch(s -> s.getStepMetaInterface() instanceof MappingOutputMeta);\nif (!ok) throw new IllegalStateException(\"Mapping sub-transformation needs exactly one Mapping Output step\");","typeGuard":"boolean hasMappingOutput = transMeta.getSteps() != null\n  && transMeta.getSteps().stream()\n       .anyMatch(s -> s.getStepMetaInterface() instanceof MappingOutputMeta);","tryCatchPattern":"try {\n  StepMeta out = transMeta.findMappingOutputStep();\n} catch (KettleStepException e) {\n  // add/re-add a MappingOutput step, then retry\n}","preventionTips":["Always design mapping sub-transformations with a Mapping Output step","Verify saved KTRs open cleanly and contain the MappingOutput step","Use TransMeta.verify()/repository verification before deployment"],"tags":["kettle","transformation","mapping-step","missing-step"],"backgroundTag":"empty-required-field","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"}