{"record":{"id":"d6aae1ca6ec2eab3","repo":"pentaho/pentaho-kettle","slug":"unable-to-load-the-mapping-transformation","errorCode":null,"errorMessage":"Unable to load the mapping transformation","messagePattern":"Unable to load the mapping transformation","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMappingMeta.java","lineNumber":280,"sourceCode":"\n    MappingIODefinition outputDefinition = new MappingIODefinition( null, null );\n    outputDefinition.setMainDataPath( true );\n    outputMapping = outputDefinition;\n  }\n\n  @Override\n  public void getFields( Bowl bowl, RowMetaInterface row, String origin, RowMetaInterface[] info, StepMeta nextStep,\n    VariableSpace space, Repository repository, IMetaStore metaStore ) throws KettleStepException {\n    // First load some interesting data...\n\n    // Then see which fields get added to the row.\n    //\n    TransMeta mappingTransMeta = null;\n    try {\n      mappingTransMeta =\n        loadMappingMeta( bowl, this, repository, metaStore, space, mappingParameters.isInheritingAllVariables() );\n    } catch ( KettleException e ) {\n      throw new KettleStepException( BaseMessages.getString(\n        PKG, \"SimpleMappingMeta.Exception.UnableToLoadMappingTransformation\" ), e );\n    }\n\n    // The field structure may depend on the input parameters as well (think of parameter replacements in MDX queries\n    // for instance)\n    if ( mappingParameters != null && mappingTransMeta != null ) {\n\n      // Just set the variables in the transformation statically.\n      // This just means: set a number of variables or parameter values:\n      //\n      StepWithMappingMeta.activateParams( mappingTransMeta, mappingTransMeta, space, mappingTransMeta.listParameters(),\n        mappingParameters.getVariable(), mappingParameters.getInputField(), mappingParameters.isInheritingAllVariables() );\n    }\n\n    // Keep track of all the fields that need renaming...\n    //\n    List<MappingValueRename> inputRenameList = new ArrayList<MappingValueRename>();\n","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMappingMeta.java#L262-L298","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Check the chained cause to see why loadMappingMeta failed (file not found, repository login, etc.) and fix that root problem.","Verify the mapping reference path - prefer absolute paths or ${Internal.Transformation.Filename.Directory} relative references.","If running headless, ensure the repository/metaStore connection is available and credentials are configured.","Define any variables used in the mapping reference (e.g. via kettle.properties or run configuration parameters).","Check file permissions of the referenced .ktr on the executing machine."],"exampleFix":"// before: relative path that breaks at runtime\n//   Mapping: sub_mapping.ktr\n// after: anchor to the parent transformation's directory\n//   Mapping: ${Internal.Transformation.Filename.Directory}/sub_mapping.ktr","handlingStrategy":"validation","validationCode":"// Verify the mapping file is loadable before running the parent transformation\nString mappingPath = simpleMappingMeta.getFileName();\nFile f = new File(variables.environmentSubstitute(mappingPath));\nif (!f.exists() || !f.canRead()) {\n  throw new IllegalStateException(\"Mapping transformation not found/readable: \" + f.getAbsolutePath());\n}","typeGuard":null,"tryCatchPattern":"try {\n  meta.getFields(row, origin, info, target, repository, metaStore, space);\n} catch (KettleStepException e) {\n  logError(\"Could not load mapping transformation: \" + e.getMessage());\n}","preventionTips":["Use ${Internal.Transformation.Filename.Directory} based relative references instead of working-directory-relative paths","Ensure repository connections and credentials are configured on every execution environment","Define all variables used in mapping references in kettle.properties or the run configuration"],"tags":["kettle","pdi","sub-transformation","file-not-found","configuration"],"backgroundTag":"resource-not-found","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"}