pentaho/pentaho-kettle · error · KettleException

MappingDialog.Exception.NoMappingSpecified

MappingDialog.Exception.NoMappingSpecified

Error message

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

What it means

Thrown by MappingHelper.getFieldsFromMappingTrans when the Mapping step has no valid sub-transformation (mappingTransMeta == null) while resolving field metadata. Pentaho requires a mapping/sub-transformation to be specified before it can determine the step's output fields.

Solutions

1. Open the Mapping step dialog and specify a valid sub-transformation file or repository object
2. Verify the transformation path/file exists at the configured location
3. Check repository connectivity and permissions if the mapping lives in a repository
4. Re-enter the mapping reference after moving the project so relative paths resolve

Example fix

// before
mappingMeta.setFileName(null); // no sub-transformation chosen
// after
mappingMeta.setFileName("${Internal.Transformation.Filename.Directory}/child.ktr");

// before getFields
if (mappingMeta.getDirectory() == null && Utils.isEmpty(mappingMeta.getFileName()) && mappingMeta.getTransName() == null) {
  throw new IllegalStateException("No mapping sub-transformation specified");
}

boolean hasMapping(MappingMeta meta) { return !Utils.isEmpty(meta.getFileName()) || meta.getRepositoryDirectory() != null || !Utils.isEmpty(meta.getTransName()); }

try {
  meta.getFields(...);
} catch (KettleStepException e) {
  logError("No valid mapping specified: " + e.getMessage());
  // prompt user to select a sub-transformation
}

When it happens

Trigger: getFieldsFromStep -> getFieldsFromMappingTrans with a null mappingTransMeta, i.e. the Mapping step's transformation file/repository path is unset, or loadMappingMeta failed to produce a TransMeta.

Common situations: User saved the Mapping step dialog without choosing a transformation; the referenced transformation file was moved or deleted; repository connection issues prevented loading; relative paths broken after moving the project.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• MappingDialog.Exception.OneMappingInputStepRequired
• MappingDialog.Exception.OnlyOneMappingInputStepAllowed
• MappingOutput.Exception.UnableToConnectWithParentMapping
• The simple mapping step does not support multiple Mapping…
• The simple mapping step needs one Mapping Input step to…

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

Appendix: source

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

    }
  }

  private RowMetaInterface getFieldsFromParentTrans( String inputStepName, TransMeta transMeta, String stepName ) throws KettleException {
    if ( Utils.isEmpty( inputStepName ) ) {
      return transMeta.getPrevStepFields( stepName );
    } else {
      StepMeta stepMeta = transMeta.findStep( inputStepName );
      if ( stepMeta == null ) {
        throw new KettleException( BaseMessages.getString(
            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 ) );

View on GitHub (pinned to f3058517a1)