pentaho/pentaho-kettle · error · KettleStepException

MappingMeta.Exception.UnableToLoadMappingTransformation

MappingMeta.Exception.UnableToLoadMappingTransformation

Error message

Unable to load the mapping transformation

What it means

KettleStepException wrapper from MappingMeta.getFields: loadMappingMeta failed to load the referenced sub-transformation (file, repository, or metastore lookup threw). getFields cannot compute the output row structure without the mapping TransMeta, so it wraps and rethrows.

Solutions

1. Verify the sub-transformation file/path exists and variables in the path resolve
2. Check repository connectivity and permissions for the referenced transformation
3. Look at the wrapped cause exception for the underlying load failure
4. Use absolute paths or correct ${Internal.Transformation.Filename.Directory} references

Example fix

// before (broken relative path)
mappingMeta.setFileName("mappings/child.ktr"); // moved project
// after
mappingMeta.setFileName("${Internal.Transformation.Filename.Directory}/mappings/child.ktr");

// pre-flight load of the mapping
try {
  MappingMeta.loadMappingMeta(bowl, mappingMeta, repository, metaStore, space);
} catch (KettleException e) {
  logError("Mapping cannot be loaded: " + e.getMessage());
}

boolean mappingLoads(MappingMeta meta, Repository repo, IMetaStore ms, VariableSpace space) { try { MappingMeta.loadMappingMeta(null, meta, repo, ms, space); return true; } catch (KettleException e) { return false; } }

try {
  meta.getFields(row, origin, info, nextStep, space, repo, metaStore);
} catch (KettleStepException e) {
  logError("Unable to load mapping transformation: " + e.getCause(), e);
  // fix path/repository issue before retrying
}

When it happens

Trigger: getFields -> loadMappingMeta throws KettleException — missing/moved .ktr file, repository object not found, insufficient repository permissions, or invalid variables in the path that fail substitution.

Common situations: Relative file paths broken after moving the project; environment-specific variables (${...}) unresolvable at design time; repository connection down; transformation deleted or renamed in the repository.

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

• AccessInput.Log.RequiredFilesMissing
• ChangeFileEncoding.Error.SourceFileNotExists
• Error reading DBF file
• Error retrieving command string
• file [ + ArgList[0] + ] can not be found!

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

Appendix: source

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

    outputDefinition.setMainDataPath( true );
    outputMappings.add( outputDefinition );

    allowingMultipleInputs = false;
    allowingMultipleOutputs = false;
  }

  @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 );
    } catch ( KettleException e ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "MappingMeta.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 ) {

      // See if we need to pass all variables from the parent or not...
      //
      if ( mappingParameters.isInheritingAllVariables() ) {
        mappingTransMeta.copyVariablesFrom( space );
      }

      // Just set the variables in the transformation statically.
      // This just means: set a number of variables or parameter values:
      //
      List<String> subParams = Arrays.asList( mappingTransMeta.listParameters() );

View on GitHub (pinned to f3058517a1)