{"record":{"id":"2ae50771db61382b","repo":"pentaho/pentaho-kettle","slug":"mappingdialog-exception-onemappinginputsteprequired-the","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/MappingHelper.java","lineNumber":237,"sourceCode":"            PKG, \"MappingDialog.Exception.SpecifiedStepWasNotFound\", inputStepName ) );\n      }\n      return transMeta.getStepFields( stepMeta );\n    }\n  }\n\n  private RowMetaInterface getFieldsFromMappingTrans( String inputStepName, TransMeta mappingTransMeta, boolean mappingInput ) throws KettleException {\n    if ( mappingTransMeta == null ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"MappingDialog.Exception.NoMappingSpecified\" ) );\n    }\n\n    if ( Utils.isEmpty( inputStepName ) ) {\n      String[] stepNames = MappingHelper.getMappingSteps( mappingTransMeta, mappingInput );\n      if ( stepNames.length > 1 ) {\n        throw new KettleException( BaseMessages.getString(\n            PKG, \"MappingDialog.Exception.OnlyOneMappingInputStepAllowed\", \"\" + stepNames.length ) );\n      }\n      if ( stepNames.length == 0 ) {\n        throw new KettleException( BaseMessages.getString(\n            PKG, \"MappingDialog.Exception.OneMappingInputStepRequired\", \"\" + stepNames.length ) );\n      }\n      return mappingTransMeta.getStepFields( stepNames[ 0 ] );\n    } else {\n      StepMeta stepMeta = mappingTransMeta.findStep( inputStepName );\n      if ( stepMeta == null ) {\n        throw new KettleException( BaseMessages.getString(\n            PKG, \"MappingDialog.Exception.SpecifiedStepWasNotFound\", inputStepName ) );\n      }\n      return mappingTransMeta.getStepFields( stepMeta );\n    }\n  }\n\n  private JSONArray generateFieldsJSON( RowMetaInterface fields ) {\n    JSONArray rowsArray = new JSONArray();\n\n    for ( int i = 0; i < fields.getValueMetaList().size(); i++ ) {\n      JSONObject rowObject = new JSONObject();","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingHelper.java#L219-L255","documentation":"The counterpart of 1622: when no specific input step name is configured, the sub-transformation must contain exactly one 'Mapping Input' step, but none was found (stepNames.length == 0). Pentaho needs a single Mapping Input to read the incoming row structure.","triggerScenarios":"getFieldsFromMappingTrans with empty inputStepName and getMappingSteps returning an empty array because the sub-transformation has no Mapping Input step.","commonSituations":"Sub-transformation was authored with a generic 'Input'/'Text File Input' instead of a Mapping Input step; the Mapping Input step was deleted; wrong transformation file referenced (a normal .ktr with no mapping steps).","solutions":["Add a 'Mapping Input' step to the sub-transformation","Verify the referenced sub-transformation actually contains a Mapping Input step (not the wrong file)","Alternatively specify the source step name explicitly if you intentionally use a non-Mapping-Input step"],"exampleFix":"// before: child.ktr has no Mapping Input step\n// after: drag a 'Mapping Input' step into child.ktr and save before referencing it","handlingStrategy":"validation","validationCode":"// before getFields\nString[] inputs = MappingHelper.getMappingSteps(mappingTransMeta, true);\nif (Utils.isEmpty(inputStepName) && inputs.length == 0) {\n  throw new IllegalStateException(\"Sub-transformation has no Mapping Input step\");\n}","typeGuard":"boolean hasMappingInput(TransMeta mappingTransMeta) { return MappingHelper.getMappingSteps(mappingTransMeta, true).length >= 1; }","tryCatchPattern":"try {\n  fields = helper.getFieldsFromStep(...);\n} catch (KettleException e) {\n  logError(\"Missing Mapping Input step: \" + e.getMessage());\n  // add a Mapping Input step to the sub-transformation\n}","preventionTips":["Scaffold sub-transformations with a Mapping Input step from the start","Confirm the referenced file is a mapping (not a plain transformation)","Template child transformations so Mapping Input/Output steps are never omitted"],"tags":["kettle","mapping","missing-step","sub-transformation"],"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"}