pentaho/pentaho-kettle · error · KettleException

SimpleMappingDialog.Exception.UnableToFindRepositoryDirector…

Error message

SimpleMappingDialog.Exception.UnableToFindRepositoryDirectory

What it means

SimpleMappingDialog.loadTransformation resolves the directory portion of the mapping path via repository.findDirectory(realDirectory). When the repository has no directory at that path it returns null and this KettleException (SimpleMappingDialog.Exception.UnableToFindRepositoryDirectory) is thrown, meaning the referenced mapping's folder does not exist in the connected repository.

Solutions

Browse the repository and reselect the mapping in the Simple Mapping dialog so the path is regenerated
Verify the directory exists in the connected repository (Repository explorer)
Confirm you are connected to the correct repository (dev vs prod)
Restore/recreate the missing directory, or update the mapping reference to the new path

Example fix

// before: stale path after directory rename
String transPath = "/old-dir/my-mapping"; // /old-dir deleted -> findDirectory returns null
// after
String transPath = "/new-dir/my-mapping"; // reselect mapping after moving it

Defensive patterns

Strategy: validation

Validate before calling

// Java: check directory exists before loading mapping by name
RepositoryDirectoryInterface dir = repository.findDirectory( realDirectory );
if ( dir == null ) throw new IllegalStateException( "Mapping directory missing: " + realDirectory );

Type guard

boolean dirExists = realDirectory != null && repository.findDirectory( realDirectory ) != null;

Try / catch

try { loadMapping( path ); } catch ( KettleException e ) { showRepositoryBrowserToReselect(); }

Prevention

Verify the path in Repository explorer after any directory reorganization
Connect to the same repository the mapping was designed in
Use repository search to relocate mappings instead of keeping stale paths

When it happens

Trigger: Loading mapping metadata by name from a repository where the directory string parsed from transPath (everything before the last '/') does not match any repository directory.

Common situations: Mappings moved or renamed after being referenced; connecting to a different repository than the one where the mapping was designed; case-sensitivity or slash/separator differences across OS; deleted directories.

Related errors

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

Appendix: source

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

          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(
          PKG, "SimpleMappingDialog.Exception.NotConnectedToRepository.Message" ) );
      }
      RepositoryObject transInf = repository.getObjectInformation( transObjectId, RepositoryObjectType.TRANSFORMATION );
      String path = DialogUtils
        .getPath( transMeta.getRepositoryDirectory().getPath(), transInf.getRepositoryDirectory().getPath() );

View on GitHub (pinned to f3058517a1)