{"record":{"id":"954c9d3192874cc7","repo":"pentaho/pentaho-kettle","slug":"mappingmeta-exception-unabletoloadmappingtransformation","errorCode":"MappingMeta.Exception.UnableToLoadMappingTransformation","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/mapping/MappingMeta.java","lineNumber":399,"sourceCode":"    outputDefinition.setMainDataPath( true );\n    outputMappings.add( outputDefinition );\n\n    allowingMultipleInputs = false;\n    allowingMultipleOutputs = false;\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 = loadMappingMeta( bowl, this, repository, metaStore, space );\n    } catch ( KettleException e ) {\n      throw new KettleStepException( BaseMessages.getString(\n        PKG, \"MappingMeta.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 ) {\n\n      // See if we need to pass all variables from the parent or not...\n      //\n      if ( mappingParameters.isInheritingAllVariables() ) {\n        mappingTransMeta.copyVariablesFrom( space );\n      }\n\n      // Just set the variables in the transformation statically.\n      // This just means: set a number of variables or parameter values:\n      //\n      List<String> subParams = Arrays.asList( mappingTransMeta.listParameters() );\n","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingMeta.java#L381-L417","documentation":"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.","triggerScenarios":"getFields -> loadMappingMeta throws KettleException — missing/moved .ktr file, repository object not found, insufficient repository permissions, or invalid variables in the path that fail substitution.","commonSituations":"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.","solutions":["Verify the sub-transformation file/path exists and variables in the path resolve","Check repository connectivity and permissions for the referenced transformation","Look at the wrapped cause exception for the underlying load failure","Use absolute paths or correct ${Internal.Transformation.Filename.Directory} references"],"exampleFix":"// before (broken relative path)\nmappingMeta.setFileName(\"mappings/child.ktr\"); // moved project\n// after\nmappingMeta.setFileName(\"${Internal.Transformation.Filename.Directory}/mappings/child.ktr\");","handlingStrategy":"try-catch","validationCode":"// pre-flight load of the mapping\ntry {\n  MappingMeta.loadMappingMeta(bowl, mappingMeta, repository, metaStore, space);\n} catch (KettleException e) {\n  logError(\"Mapping cannot be loaded: \" + e.getMessage());\n}","typeGuard":"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; } }","tryCatchPattern":"try {\n  meta.getFields(row, origin, info, nextStep, space, repo, metaStore);\n} catch (KettleStepException e) {\n  logError(\"Unable to load mapping transformation: \" + e.getCause(), e);\n  // fix path/repository issue before retrying\n}","preventionTips":["Verify sub-transformation paths resolve with the current variable space","Check repository connectivity before running transformations that use mappings","Keep child .ktr files colocated and referenced via internal directory variables"],"tags":["kettle","mapping","load-failure","file-not-found"],"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"}