{"record":{"id":"5227496aec76d175","repo":"pentaho/pentaho-kettle","slug":"mappingdialog-exception-onlyonemappinginputstepallowed-522749","errorCode":"MappingDialog.Exception.OnlyOneMappingInputStepAllowed","errorMessage":"Without specifying specific stepnames to read from, there can only be one 'mapping input' step in the mapping and we found {0}.","messagePattern":"Without specifying specific stepnames to read from, there can only be one 'mapping input' step in the mapping and we found (.+?)\\.","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingHelper.java","lineNumber":233,"sourceCode":"    } else {\n      StepMeta stepMeta = transMeta.findStep( inputStepName );\n      if ( stepMeta == null ) {\n        throw new KettleException( BaseMessages.getString(\n            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 ) {","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingHelper.java#L215-L251","documentation":"Thrown when no specific input step name is given and the sub-transformation contains more than one 'Mapping Input' step. Without an explicit step name Pentaho cannot decide which Mapping Input step's fields to use, so it rejects the ambiguity.","triggerScenarios":"getFieldsFromMappingTrans with empty inputStepName and MappingHelper.getMappingSteps(...) returning length > 1 Mapping Input steps in the sub-transformation.","commonSituations":"Developer added a second Mapping Input step to a sub-transformation that the parent Mapping step references generically (input step left unspecified in the mapping definition).","solutions":["Remove or disable the extra Mapping Input step so exactly one remains","Specify the input step name explicitly in the Mapping step dialog (Input Source tab) so the ambiguity disappears","Enable multi-input on the mapping definition and configure all input mappings explicitly"],"exampleFix":"// before: sub-transformation has two Mapping Input steps, no step specified\nString inputStepName = null; // ambiguous\n// after\nString inputStepName = \"Mapping Input 1\"; // explicitly chosen in dialog","handlingStrategy":"validation","validationCode":"// before getFields\nString[] inputs = MappingHelper.getMappingSteps(mappingTransMeta, true);\nif (!Utils.isEmpty(inputStepName) == false && inputs.length > 1) {\n  throw new IllegalStateException(\"Specify an input step: found \" + inputs.length + \" Mapping Input steps\");\n}","typeGuard":"boolean unambiguousInput(String inputStepName, String[] mappingInputSteps) { return !Utils.isEmpty(inputStepName) || mappingInputSteps.length <= 1; }","tryCatchPattern":"try {\n  fields = helper.getFieldsFromStep(...);\n} catch (KettleException e) {\n  logError(\"Ambiguous mapping input: \" + e.getMessage());\n  // reconfigure the mapping definition to name an input step\n}","preventionTips":["Keep exactly one Mapping Input step per sub-transformation unless naming steps explicitly","Enable multi-input mode when you intentionally add several Mapping Input steps","Review sub-transformation changes after adding steps used by parent mappings"],"tags":["kettle","mapping","ambiguous-config","sub-transformation"],"backgroundTag":"conflicting-config-options","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"}