{"record":{"id":"5f097bf855ad8189","repo":"pentaho/pentaho-kettle","slug":"mappingdialog-exception-onemappinginputsteprequired","errorCode":"MappingDialog.Exception.OneMappingInputStepRequired","errorMessage":"The specified mapping needs a single 'mapping input' step to work with, but we couldn't find one.","messagePattern":"The specified mapping needs a single 'mapping input' step to work with, but we couldn't find one\\.","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/mapping/Mapping.java","lineNumber":373,"sourceCode":"        // Let's read data from all the previous steps we find...\n        // The origin is the previous step\n        // The target is the Mapping Input step.\n        //\n        sourceSteps = new StepInterface[prevSteps.size()];\n        for ( int s = 0; s < sourceSteps.length; s++ ) {\n          sourceSteps[s] = getTrans().findRunThread( prevSteps.get( s ).getName() );\n        }\n      }\n\n      // What step are we writing to?\n      MappingInput mappingInputTarget = null;\n      MappingInput[] mappingInputSteps = mappingData.getMappingTrans().findMappingInput();\n      if ( Utils.isEmpty( inputDefinition.getOutputStepname() ) ) {\n        // No target was specifically specified.\n        // That means we only expect one \"mapping input\" step in the mapping...\n\n        if ( mappingInputSteps.length == 0 ) {\n          throw new KettleException( BaseMessages\n              .getString( PKG, \"MappingDialog.Exception.OneMappingInputStepRequired\" ) );\n        }\n        if ( mappingInputSteps.length > 1 ) {\n          throw new KettleException( BaseMessages.getString( PKG,\n              \"MappingDialog.Exception.OnlyOneMappingInputStepAllowed\", \"\" + mappingInputSteps.length ) );\n        }\n\n        mappingInputTarget = mappingInputSteps[0];\n      } else {\n        // A target step was specified. See if we can find it...\n        for ( int s = 0; s < mappingInputSteps.length && mappingInputTarget == null; s++ ) {\n          if ( mappingInputSteps[s].getStepname().equals( inputDefinition.getOutputStepname() ) ) {\n            mappingInputTarget = mappingInputSteps[s];\n          }\n        }\n        // If we still didn't find it it's a drag.\n        if ( mappingInputTarget == null ) {\n          throw new KettleException( BaseMessages.getString( PKG, \"MappingDialog.Exception.StepNameNotFound\",","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mapping/Mapping.java#L355-L391","documentation":"When no explicit target/output step name is given for a mapping input definition, the Mapping step expects the sub-transformation to contain exactly one 'Mapping Input' step. If findMappingInput() returns zero such steps, this exception is thrown because there is nothing to feed rows into.","triggerScenarios":"prepareMappingExecution() handling an input definition with empty outputStepname, while the sub-transformation contains no Mapping Input step at all (mappingInputSteps.length == 0).","commonSituations":"Building a sub-transformation and forgetting to add a 'Mapping Input' step; using a transformation as a mapping that was designed as a standalone transformation; wrong transformation selected in the Mapping step dialog.","solutions":["Open the sub-transformation and add a 'Mapping Input' step.","Verify the Mapping step points at the intended sub-transformation that contains a Mapping Input step.","If the sub-transformation legitimately has multiple mapping inputs, specify the target step name explicitly in the Mapping dialog's input mapping table.","Re-export/clone the mapping from a known-good template that includes Mapping Input/Output steps."],"exampleFix":"null","handlingStrategy":"validation","validationCode":"MappingMeta mm = (MappingMeta) stepMeta.getStepMetaInterface();\nboolean noTarget = mm.getInputMappings().stream()\n    .allMatch(d -> Utils.isEmpty(d.getOutputStepname()));\nif (noTarget && mappingTransMeta.findMappingInputSteps().isEmpty()) {\n  throw new IllegalStateException(\"Sub-transformation has no 'Mapping Input' step\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  mapping.init();\n} catch (KettleException e) {\n  if (String.valueOf(e.getMessage()).contains(\"'mapping input' step\")) {\n    logError(\"Add a 'Mapping Input' step to the sub-transformation\", e);\n  } else { throw e; }\n}","preventionTips":["Always include exactly one 'Mapping Input' step in any transformation used as a mapping.","Verify the sub-transformation referenced in the Mapping dialog is the intended file.","Use PDI's mapping template when creating new sub-transformations.","Validate ktr contents after import/export operations."],"tags":["pdi","kettle","mapping-step","mapping-input","missing-step"],"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"}