pentaho/pentaho-kettle · error · KettleStepException

Unable to load the mapping transformation

Error message

Unable to load the mapping transformation

What it means

SimpleMappingMeta.getFields needs the sub-transformation's metadata to compute the fields the mapping produces, so it calls loadMappingMeta to load the referenced transformation. If that load throws a KettleException (missing file, repository error, invalid reference), it is wrapped in a KettleStepException with the message 'Unable to load the mapping transformation'.

Solutions

  1. Check the chained cause to see why loadMappingMeta failed (file not found, repository login, etc.) and fix that root problem.
  2. Verify the mapping reference path - prefer absolute paths or ${Internal.Transformation.Filename.Directory} relative references.
  3. If running headless, ensure the repository/metaStore connection is available and credentials are configured.
  4. Define any variables used in the mapping reference (e.g. via kettle.properties or run configuration parameters).
  5. Check file permissions of the referenced .ktr on the executing machine.

Example fix

// before: relative path that breaks at runtime
//   Mapping: sub_mapping.ktr
// after: anchor to the parent transformation's directory
//   Mapping: ${Internal.Transformation.Filename.Directory}/sub_mapping.ktr
Defensive patterns

Strategy: validation

Validate before calling

// Verify the mapping file is loadable before running the parent transformation
String mappingPath = simpleMappingMeta.getFileName();
File f = new File(variables.environmentSubstitute(mappingPath));
if (!f.exists() || !f.canRead()) {
  throw new IllegalStateException("Mapping transformation not found/readable: " + f.getAbsolutePath());
}

Try / catch

try {
  meta.getFields(row, origin, info, target, repository, metaStore, space);
} catch (KettleStepException e) {
  logError("Could not load mapping transformation: " + e.getMessage());
}

Prevention

When it happens

Trigger: During getFields (transformation field resolution, e.g. Spoon 'Get fields' or hop propagation), loadMappingMeta() fails because the mapping's TransMeta cannot be loaded from file, repository, or metaStore with the given variables space.

Common situations: Mapping .ktr file moved/deleted or path wrong; running from a different working directory so relative paths break; repository connection unavailable; variables used in the mapping reference not defined in the variables space; file exists but is unreadable (permissions).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMappingMeta.java:280

    MappingIODefinition outputDefinition = new MappingIODefinition( null, null );
    outputDefinition.setMainDataPath( true );
    outputMapping = outputDefinition;
  }

  @Override
  public void getFields( Bowl bowl, RowMetaInterface row, String origin, RowMetaInterface[] info, StepMeta nextStep,
    VariableSpace space, Repository repository, IMetaStore metaStore ) throws KettleStepException {
    // First load some interesting data...

    // Then see which fields get added to the row.
    //
    TransMeta mappingTransMeta = null;
    try {
      mappingTransMeta =
        loadMappingMeta( bowl, this, repository, metaStore, space, mappingParameters.isInheritingAllVariables() );
    } catch ( KettleException e ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "SimpleMappingMeta.Exception.UnableToLoadMappingTransformation" ), e );
    }

    // The field structure may depend on the input parameters as well (think of parameter replacements in MDX queries
    // for instance)
    if ( mappingParameters != null && mappingTransMeta != null ) {

      // Just set the variables in the transformation statically.
      // This just means: set a number of variables or parameter values:
      //
      StepWithMappingMeta.activateParams( mappingTransMeta, mappingTransMeta, space, mappingTransMeta.listParameters(),
        mappingParameters.getVariable(), mappingParameters.getInputField(), mappingParameters.isInheritingAllVariables() );
    }

    // Keep track of all the fields that need renaming...
    //
    List<MappingValueRename> inputRenameList = new ArrayList<MappingValueRename>();

View on GitHub (pinned to f3058517a1)