pentaho/pentaho-kettle · error · KettleException

SimpleMappingDialog.Exception.NoValidMappingDetailsFound

Error message

SimpleMappingDialog.Exception.NoValidMappingDetailsFound

What it means

SimpleMappingDialog.loadTransformation parses a repository transformation path of the form /directory/transformation. If after splitting the path either the directory part or the transformation name is empty, it throws this KettleException (SimpleMappingDialog.Exception.NoValidMappingDetailsFound) because a mapping (sub-transformation) reference cannot be resolved without both parts.

Solutions

  1. Set the mapping transformation reference to a full repository path like /public/subflows/my-mapping
  2. Re-open the Simple Mapping ( Mapping ) step dialog and reselect the mapping transformation
  3. Verify the mapping still exists in the repository and the reference was not orphaned by a rename/move
  4. If loading from file, ensure the mapping file path was supplied rather than a repository path

Example fix

// before
mappingTransMeta = loadTransformation( "/my-mapping" ); // no directory part -> throws
// after
mappingTransMeta = loadTransformation( "/public/subflows/my-mapping" );
Defensive patterns

Strategy: validation

Validate before calling

// Java: validate mapping path has directory and name before loading
int idx = transPath.lastIndexOf( '/' );
boolean valid = idx > 0 && !transPath.substring( 0, idx ).isEmpty() && !transPath.substring( idx + 1 ).isEmpty();

Type guard

boolean isFullRepoPath = transPath != null && transPath.contains( "/" ) && transPath.lastIndexOf( '/' ) < transPath.length() - 1;

Try / catch

try { loadTransformation( transPath ); } catch ( KettleException e ) { promptUserToReselectMapping(); }

Prevention

When it happens

Trigger: Loading mapping metadata when SpecifyMerge is by name from repository and the stored transPath lacks a '/' separator or is empty/blank, so realDirectory or realTransname ends up empty after substring parsing.

Common situations: Mapping step configured with a bare transformation name without a repository path; copied job/trans metadata referencing a mapping that no longer exists at the saved path; manual edits to transformation XML that blank the mapping path.

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/26d84974f81e1940. Report an issue: GitHub.

Appendix: source

Thrown at ui/src/main/java/org/pentaho/di/ui/trans/steps/simplemapping/SimpleMappingDialog.java:409

      case REPOSITORY_BY_NAME:
        if ( Utils.isEmpty( filename ) ) {
          return;
        }
        if ( filename.endsWith( ".ktr" ) ) {
          filename = filename.replace( ".ktr", "" );
          wPath.setText( filename );
        }
        String transPath = transMeta.environmentSubstitute( filename );
        String realTransname = transPath;
        String realDirectory = "";
        int index = transPath.lastIndexOf( "/" );
        if ( index != -1 ) {
          realTransname = transPath.substring( index + 1 );
          realDirectory = transPath.substring( 0, index );
        }

        if ( Utils.isEmpty( realDirectory ) || Utils.isEmpty( realTransname ) ) {
          throw new KettleException(
            BaseMessages.getString( PKG, "SimpleMappingDialog.Exception.NoValidMappingDetailsFound" ) );
        }
        RepositoryDirectoryInterface repdir = repository.findDirectory( realDirectory );
        if ( repdir == null ) {
          throw new KettleException( BaseMessages.getString(
            PKG, "SimpleMappingDialog.Exception.UnableToFindRepositoryDirectory" ) );
        }
        loadRepositoryTrans( realTransname, repdir );
        break;
      default:
        break;
    }
  }

  private void getByReferenceData( ObjectId transObjectId ) {
    try {
      if ( repository == null ) {
        throw new KettleException( BaseMessages.getString(

View on GitHub (pinned to f3058517a1)