pentaho/pentaho-kettle · error · KettleStepException

TransMeta.Exception.OnlyOneMappingOutputStepAllowed

Error message

TransMeta.Exception.OnlyOneMappingOutputStepAllowed

What it means

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.

Solutions

  1. Delete the redundant MappingOutput step(s), leaving exactly one
  2. Split into separate mapping sub-transformations if multiple outputs are truly required
  3. Reference the desired output step explicitly by name instead of auto-detection

Example fix

// before
// mapping.ktr has two MappingOutput steps
StepMeta sm = transMeta.findMappingOutputStep(null); // throws
// after
// remove the duplicate MappingOutput in Spoon, then:
StepMeta sm = transMeta.findMappingOutputStep(null);
Defensive patterns

Strategy: type-guard

Validate before calling

long count = Arrays.stream(transMeta.getStepsArray())
    .filter(s -> "MappingOutput".equals(s.getStepID())).count();
if (count > 1) throw new IllegalStateException("Sub-transformation has " + count + " MappingOutput steps; must have exactly 1");

Try / catch

try {
  StepMeta sm = transMeta.findMappingOutputStep(null);
} catch (KettleStepException e) {
  logger.error("MappingOutput count violation in {}: remove duplicate MappingOutput steps", transMeta.getName());
  throw e;
}

Prevention

When it happens

Trigger: Calling findMappingOutputStep(null/empty name) on a transformation containing multiple MappingOutput steps.

Common situations: Duplicated MappingOutput step from copy/paste in a mapping sub-transformation; merging two mappings into one file; template copies not cleaned up.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/TransMeta.java:6164

   *           if any errors occur during the search
   */
  public StepMeta findMappingOutputStep( String stepname ) throws KettleStepException {
    if ( !Utils.isEmpty( stepname ) ) {
      StepMeta stepMeta = findStep( stepname ); // TODO verify that it's a mapping output step.
      if ( stepMeta == null ) {
        throw new KettleStepException( BaseMessages.getString(
          PKG, "TransMeta.Exception.StepNameNotFound", stepname ) );
      }
      return stepMeta;
    } else {
      // Find the first mapping output step that fits the bill.
      StepMeta stepMeta = null;
      for ( StepMeta mappingStep : steps ) {
        if ( mappingStep.getStepID().equals( "MappingOutput" ) ) {
          if ( stepMeta == null ) {
            stepMeta = mappingStep;
          } else if ( stepMeta != null ) {
            throw new KettleStepException( BaseMessages.getString(
              PKG, "TransMeta.Exception.OnlyOneMappingOutputStepAllowed", "2" ) );
          }
        }
      }
      if ( stepMeta == null ) {
        throw new KettleStepException( BaseMessages.getString(
          PKG, "TransMeta.Exception.OneMappingOutputStepRequired" ) );
      }
      return stepMeta;
    }
  }

  /**
   * Gets a list of the resource dependencies.
   *
   * @return a list of ResourceReferences
   */
  public List<ResourceReference> getResourceDependencies() {

View on GitHub (pinned to f3058517a1)