What causes "Source steps should not be empty." in pentaho/pentaho-kettle?

Pass a non-null array; use new StepInterface[0] when there are genuinely no source steps.

pentaho/pentaho-kettle · error · IllegalArgumentException

MappingInput.Exception.IllegalArgumentSourceStep

MappingInput.Exception.IllegalArgumentSourceStep

Error message

Source steps should not be empty.

What it means

setConnectorSteps() validates its arguments before wiring the parent transformation's source steps to this Mapping Input step. Passing a null array of source steps throws an IllegalArgumentException. The library requires a non-null (possibly empty) array so it can always record data.sourceSteps.

Solutions

Pass a non-null array; use new StepInterface[0] when there are genuinely no source steps.
Ensure the parent transformation was built/loaded correctly so the Mapping step's input hops resolve to real steps.
Call setConnectorSteps only after the parent Trans has prepared its threads and step instances exist.

Example fix

// before
mappingInput.setConnectorSteps(null, renames, "Mapping input");
// after
StepInterface[] sourceSteps = mappingInputStep.getStepInterface();
mappingInput.setConnectorSteps(sourceSteps == null ? new StepInterface[0] : sourceSteps, renames, "Mapping input");

Defensive patterns

Strategy: type-guard

Validate before calling

if (sourceSteps == null) {
  sourceSteps = new StepInterface[0]; // normalize before calling setConnectorSteps
}

Type guard

boolean isUsableSourceSteps(StepInterface[] steps) { return steps != null; }

Try / catch

try {
  mappingInput.setConnectorSteps(steps, renames, name);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Source steps should not be empty")) {
    // resolve parent step instances before wiring
  }
  throw e;
}

Prevention

Default to an empty array, never null, for step arrays.
Resolve StepInterface instances from a prepared Trans before calling setConnectorSteps.
Add unit tests mirroring testSetConnectorStepsWithNullArguments in your integration code.

When it happens

Trigger: Calling mappingInput.setConnectorSteps(null, valueRenames, stepname) directly, or a code path in prepareMappingExecution that resolves no source steps and passes null instead of an empty array.

Common situations: Custom Java code embedding a mapping transformation; testing (e.g., testSetConnectorStepsWithNullArguments); framework integration bugs where the Mapping step's input hops were never resolved.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mappinginput/MappingInput.java:181

    } else {
      putRow( data.outputRowMeta, row );
    }

    return true;
  }

  public boolean init( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (MappingInputMeta) smi;
    data = (MappingInputData) sdi;

    return super.init( smi, sdi );
  }

  public void setConnectorSteps( StepInterface[] sourceSteps, List<MappingValueRename> valueRenames,
      String mappingStepname ) {

    if ( sourceSteps == null ) {
      throw new IllegalArgumentException( BaseMessages
          .getString( PKG, "MappingInput.Exception.IllegalArgumentSourceStep" ) );
    }

    if ( valueRenames == null ) {
      throw new IllegalArgumentException( BaseMessages
          .getString( PKG, "MappingInput.Exception.IllegalArgumentValueRename" ) );
    }

    if ( sourceSteps.length != 0 ) {
      if ( mappingStepname == null ) {
        throw new IllegalArgumentException( BaseMessages
          .getString( PKG, "MappingInput.Exception.IllegalArgumentStepName" ) );
      }
    }

    for ( StepInterface sourceStep : sourceSteps ) {

      // We don't want to add the mapping-to-mapping rowset

View on GitHub (pinned to f3058517a1)