pentaho/pentaho-kettle · error · KettleException

MappingDialog.Exception.OneMappingInputStepRequired

MappingDialog.Exception.OneMappingInputStepRequired

Error message

The specified mapping needs a single 'mapping input' step to work with, but we couldn't find one.

What it means

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.

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

Example fix

// before: child.ktr has no Mapping Input step
// after: drag a 'Mapping Input' step into child.ktr and save before referencing it

Defensive patterns

Strategy: validation

Validate before calling

// before getFields
String[] inputs = MappingHelper.getMappingSteps(mappingTransMeta, true);
if (Utils.isEmpty(inputStepName) && inputs.length == 0) {
  throw new IllegalStateException("Sub-transformation has no Mapping Input step");
}

Type guard

boolean hasMappingInput(TransMeta mappingTransMeta) { return MappingHelper.getMappingSteps(mappingTransMeta, true).length >= 1; }

Try / catch

try {
  fields = helper.getFieldsFromStep(...);
} catch (KettleException e) {
  logError("Missing Mapping Input step: " + e.getMessage());
  // add a Mapping Input step to the sub-transformation
}

Prevention

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

When it happens

Trigger: getFieldsFromMappingTrans with empty inputStepName and getMappingSteps returning an empty array because the sub-transformation has no Mapping Input step.

Common situations: 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).

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/2ae50771db61382b. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingHelper.java:237

            PKG, "MappingDialog.Exception.SpecifiedStepWasNotFound", inputStepName ) );
      }
      return transMeta.getStepFields( stepMeta );
    }
  }

  private RowMetaInterface getFieldsFromMappingTrans( String inputStepName, TransMeta mappingTransMeta, boolean mappingInput ) throws KettleException {
    if ( mappingTransMeta == null ) {
      throw new KettleException( BaseMessages.getString( PKG, "MappingDialog.Exception.NoMappingSpecified" ) );
    }

    if ( Utils.isEmpty( inputStepName ) ) {
      String[] stepNames = MappingHelper.getMappingSteps( mappingTransMeta, mappingInput );
      if ( stepNames.length > 1 ) {
        throw new KettleException( BaseMessages.getString(
            PKG, "MappingDialog.Exception.OnlyOneMappingInputStepAllowed", "" + stepNames.length ) );
      }
      if ( stepNames.length == 0 ) {
        throw new KettleException( BaseMessages.getString(
            PKG, "MappingDialog.Exception.OneMappingInputStepRequired", "" + stepNames.length ) );
      }
      return mappingTransMeta.getStepFields( stepNames[ 0 ] );
    } else {
      StepMeta stepMeta = mappingTransMeta.findStep( inputStepName );
      if ( stepMeta == null ) {
        throw new KettleException( BaseMessages.getString(
            PKG, "MappingDialog.Exception.SpecifiedStepWasNotFound", inputStepName ) );
      }
      return mappingTransMeta.getStepFields( stepMeta );
    }
  }

  private JSONArray generateFieldsJSON( RowMetaInterface fields ) {
    JSONArray rowsArray = new JSONArray();

    for ( int i = 0; i < fields.getValueMetaList().size(); i++ ) {
      JSONObject rowObject = new JSONObject();

View on GitHub (pinned to f3058517a1)