{"record":{"id":"d37baa933aed23f2","repo":"pentaho/pentaho-kettle","slug":"mappingmeta-exception-unabletofindmappingdefinition","errorCode":"MappingMeta.Exception.UnableToFindMappingDefinition","errorMessage":"Unable to find appropriate mapping definition to determine output row metadata.","messagePattern":"Unable to find appropriate mapping definition to determine output row metadata\\.","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingMeta.java","lineNumber":550,"sourceCode":"          //\n          mappingOutputDefinition = definition;\n        }\n      }\n    } else {\n      // Is there an output mapping definition for this step?\n      // If so, we can look up the Mapping output step to see what has changed.\n      //\n\n      for ( MappingIODefinition definition : outputMappings ) {\n        if ( nextStep.getName().equals( definition.getOutputStepname() )\n          || definition.isMainDataPath() || Utils.isEmpty( definition.getOutputStepname() ) ) {\n          mappingOutputDefinition = definition;\n        }\n      }\n    }\n\n    if ( mappingOutputDefinition == null ) {\n      throw new KettleStepException( BaseMessages.getString(\n        PKG, \"MappingMeta.Exception.UnableToFindMappingDefinition\" ) );\n    }\n\n    // OK, now find the mapping output step in the mapping...\n    // This method in TransMeta takes into account a number of things, such as\n    // the step not specified, etc.\n    // The method never returns null but throws an exception.\n    //\n    StepMeta mappingOutputStep =\n      mappingTransMeta.findMappingOutputStep( mappingOutputDefinition.getInputStepname() );\n\n    // We know it's a mapping output step...\n    MappingOutputMeta mappingOutputMeta = (MappingOutputMeta) mappingOutputStep.getStepMetaInterface();\n\n    // Change a few columns.\n    mappingOutputMeta.setOutputValueRenames( mappingOutputDefinition.getValueRenames() );\n\n    // Perhaps we need to change a few input columns back to the original?","sourceCodeStart":532,"sourceCodeEnd":568,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingMeta.java#L532-L568","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Open the Mapping step dialog (Output Source tab) and set a valid output step/definition","Verify the Mapping Output step exists in the sub-transformation and its name matches the definition","Reconfigure the output mapping after any renames in the sub-transformation"],"exampleFix":"// before\nmappingDefinition.setOutputStepname(null); // no matching output definition\n// after\nmappingDefinition.setOutputStepname(\"Mapping Output\"); // matches step in child.ktr","handlingStrategy":"validation","validationCode":"// before getFields\nboolean hasOutputDef = meta.getMappingOutputDefinitions().stream()\n  .anyMatch(d -> !Utils.isEmpty(d.getOutputStepname()));\nif (!hasOutputDef) {\n  logError(\"No mapping output definition configured\");\n}","typeGuard":"boolean hasMatchingOutputDefinition(MappingMeta meta, String targetStepName) { return meta.getMappingOutputDefinitions().stream().anyMatch(d -> targetStepName.equals(d.getOutputStepname())); }","tryCatchPattern":"try {\n  meta.getFields(...);\n} catch (KettleStepException e) {\n  logError(\"No matching mapping output definition: \" + e.getMessage());\n  // configure the Output Source tab in the Mapping dialog\n}","preventionTips":["Always configure the Output Source tab when creating a Mapping step","Keep Mapping Output step names stable in the sub-transformation","Re-check output definitions after swapping or refactoring the child transformation"],"tags":["kettle","mapping","missing-definition","configuration"],"backgroundTag":"missing-required-config-field","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"}