pentaho/pentaho-kettle · error · KettleStepException

MappingMeta.Exception.UnableToFindMappingDefinition

MappingMeta.Exception.UnableToFindMappingDefinition

Error message

Unable to find appropriate mapping definition to determine output row metadata.

What it means

Thrown in MappingMeta.getFields when no mapping output definition matches the target steps being resolved — after scanning the definitions, mappingOutputDefinition remains null. The step cannot determine output row metadata without a matching output definition.

Solutions

  1. Open the Mapping step dialog (Output Source tab) and set a valid output step/definition
  2. Verify the Mapping Output step exists in the sub-transformation and its name matches the definition
  3. Reconfigure the output mapping after any renames in the sub-transformation

Example fix

// before
mappingDefinition.setOutputStepname(null); // no matching output definition
// after
mappingDefinition.setOutputStepname("Mapping Output"); // matches step in child.ktr
Defensive patterns

Strategy: validation

Validate before calling

// before getFields
boolean hasOutputDef = meta.getMappingOutputDefinitions().stream()
  .anyMatch(d -> !Utils.isEmpty(d.getOutputStepname()));
if (!hasOutputDef) {
  logError("No mapping output definition configured");
}

Type guard

boolean hasMatchingOutputDefinition(MappingMeta meta, String targetStepName) { return meta.getMappingOutputDefinitions().stream().anyMatch(d -> targetStepName.equals(d.getOutputStepname())); }

Try / catch

try {
  meta.getFields(...);
} catch (KettleStepException e) {
  logError("No matching mapping output definition: " + e.getMessage());
  // configure the Output Source tab in the Mapping dialog
}

Prevention

When it happens

Trigger: getFields: the loop selecting the MappingOutputDefinition whose step name/target matches the current output step finds no match (e.g. output step name unset, changed, or no definition configured for the mapping output path).

Common situations: The Mapping Output step in the sub-transformation was renamed or removed; the mapping definition's output step name is blank; multiple output mappings configured but none matching the target step; sub-transformation swapped for one with different outputs.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingMeta.java:550

          //
          mappingOutputDefinition = definition;
        }
      }
    } else {
      // Is there an output mapping definition for this step?
      // If so, we can look up the Mapping output step to see what has changed.
      //

      for ( MappingIODefinition definition : outputMappings ) {
        if ( nextStep.getName().equals( definition.getOutputStepname() )
          || definition.isMainDataPath() || Utils.isEmpty( definition.getOutputStepname() ) ) {
          mappingOutputDefinition = definition;
        }
      }
    }

    if ( mappingOutputDefinition == null ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "MappingMeta.Exception.UnableToFindMappingDefinition" ) );
    }

    // OK, now find the mapping output step in the mapping...
    // This method in TransMeta takes into account a number of things, such as
    // the step not specified, etc.
    // The method never returns null but throws an exception.
    //
    StepMeta mappingOutputStep =
      mappingTransMeta.findMappingOutputStep( mappingOutputDefinition.getInputStepname() );

    // We know it's a mapping output step...
    MappingOutputMeta mappingOutputMeta = (MappingOutputMeta) mappingOutputStep.getStepMetaInterface();

    // Change a few columns.
    mappingOutputMeta.setOutputValueRenames( mappingOutputDefinition.getValueRenames() );

    // Perhaps we need to change a few input columns back to the original?

View on GitHub (pinned to f3058517a1)