pentaho/pentaho-kettle · error · KettleException

No mapping (sub-transformation) was specified or it was not…

Error message

No mapping (sub-transformation) was specified or it was not a valid one.

What it means

SimpleMappingHelper.getFieldsFromStep resolves field layout for a mapping step. When asked for the sub-transformation (non-parent) side with input=true, it must locate the Mapping Input step in the mapping's TransMeta; if mappingTransMeta is null (no mapping was specified or it failed to load) a KettleException with the localized 'No mapping specified' message is thrown.

Solutions

Set a valid mapping transformation on the Simple Mapping step (specify file or repository entry) before running or checking the transformation.
Confirm the mapping path/expression resolves at runtime - check that any variables used in the mapping reference are defined (kettle.properties, parameter injection).
Re-open and re-save the step dialog to rebuild the mapping reference if it was lost during an XML merge or import.
Verify the referenced transformation file still exists and is readable from the environment running the transformation.

Example fix

// before: Simple Mapping step has no mapping specified
//   Mapping transformation: (empty)
// after: point at an existing sub-transformation
//   Mapping transformation: ${Internal.Transformation.Filename.Directory}/sub_mapping.ktr

Defensive patterns

Strategy: validation

Validate before calling

// Ensure a mapping reference is set before resolving fields
if (simpleMappingMeta.getMappingTransformationName() == null
    && simpleMappingMeta.getFileName() == null) {
  throw new IllegalStateException("Simple Mapping step '" + stepname + "' has no mapping transformation specified");
}

Try / catch

try {
  RowMetaInterface fields = helper.getFieldsFromStep(transMeta, mappingTransMeta, stepMeta, false, true);
} catch (KettleException e) {
  logError("No valid mapping specified for Simple Mapping step: " + e.getMessage());
}

Prevention

Configure the mapping reference (file or repository entry) immediately after adding the step
Prefer variables with defaults defined in kettle.properties so references resolve in all environments
Run 'Verify transformations' before production deployments to catch empty mapping references

When it happens

Trigger: Called via sourceRowMeta()/targetRowMeta() with parent=false and input=true while the mappingTransMeta parameter is null - i.e. the Simple Mapping step's mapping transformation reference is empty or could not be resolved before this call.

Common situations: Mapping reference never configured on the step; the referenced transformation file/repository path is blank after an import/export or version-control merge; the mapping field is populated only via a variable that was not set at metadata-inspection time (e.g. during transformation checking in Spoon).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMappingHelper.java:178

    }

    return response;
  }

  TransMeta loadSimpleMappingMeta( TransMeta transMeta, SimpleMappingMeta simpleMappingMeta ) throws KettleException {
    return StepWithMappingMeta.loadMappingMeta( transMeta.getBowl(), simpleMappingMeta,
        transMeta.getRepository(),
        transMeta.getMetaStore(), transMeta,
        true );
  }

  public RowMetaInterface getFieldsFromStep( TransMeta transMeta, TransMeta mappingTransMeta, StepMeta stepMeta, boolean parent, boolean input ) throws KettleException {
    if ( input ) {
      if ( parent ) {
        return transMeta.getPrevStepFields( stepMeta );
      } else {
        if ( mappingTransMeta == null ) {
          throw new KettleException( BaseMessages.getString(
              PKG, "SimpleMappingDialog.Exception.NoMappingSpecified" ) );
        }
        StepMeta mappingInputStepMeta = mappingTransMeta.findMappingInputStep( null );
        return mappingTransMeta.getStepFields( mappingInputStepMeta );
      }
    } else {
      StepMeta mappingOutputStepMeta = mappingTransMeta.findMappingOutputStep( null );
      return mappingTransMeta.getStepFields( mappingOutputStepMeta );
    }
  }

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

    for ( int i = 0; i < fields.getValueMetaList().size(); i++ ) {
      JSONObject rowObject = new JSONObject();
      rowObject.put( "type", fields.getValueMeta( i ).getTypeDesc() );
      rowObject.put( "name", fields.getValueMeta( i ).getName() );

View on GitHub (pinned to f3058517a1)