What causes "Unable to find repository directory [ ]" in pentaho/pentaho-kettle?

Verify the directory exists: browse the repository tree in Spoon or call rep.loadRepositoryDirectoryTree().findDirectory(dir) yourself and correct the path in the step/entry configuration.

pentaho/pentaho-kettle · error · KettleException

Unable to find repository directory

Error message

Unable to find repository directory [<realDirectory>]

What it means

Thrown by MetaFileLoaderImpl.getMetaFromRepository after resolving realDirectory from the meta path: rep.loadRepositoryDirectoryTree().findDirectory(realDirectory) returned null, meaning the directory does not exist in the repository (or the user lacks access to it). The loader aborts before attempting to load the transformation/job object. This is a repository lookup failure, not a file-system failure.

Solutions

Verify the directory exists: browse the repository tree in Spoon or call rep.loadRepositoryDirectoryTree().findDirectory(dir) yourself and correct the path in the step/entry configuration.
Confirm you are connected to the intended repository and that the user has read permission on the folder.
Re-point the step/entry to the moved/renamed location, or recreate the folder at the referenced path.
Resolve any variables in the path and check normalization (double slashes, leading/trailing separators) against normalizeSlashes behavior.
Pre-check in calling code: resolve the directory before loading and give a clear message listing the requested path.

Example fix

// before
RepositoryDirectoryInterface dir = rep.loadRepositoryDirectoryTree().findDirectory("/home/admin");
// dir == null -> KettleException "Unable to find repository directory [/home/admin]"

// after
RepositoryDirectoryInterface dir = rep.loadRepositoryDirectoryTree().findDirectory(realDirectory);
if (dir == null) {
  throw new KettleException("Directory " + realDirectory + " not found in repository " + rep.getName()
    + ". Available: " + rep.loadRepositoryDirectoryTree().getDisplayText("/"));
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Java caller, pre-flight directory check
RepositoryDirectoryInterface dir =
  rep.loadRepositoryDirectoryTree().findDirectory(realDirectory);
if (dir == null) {
  throw new IllegalArgumentException("Repository directory missing: " + realDirectory
    + " in repository " + rep.getName());
}

Try / catch

try {
  T meta = loader.getMetaForEntry(bowl, rep, metaStore, space);
} catch (KettleException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unable to find repository directory")) {
    throw new ConfigurationException("Repository folder missing/renamed: " + e.getMessage(), e);
  }
  throw e;
}

Prevention

Avoid renaming/deleting repository folders without updating all steps/entries that reference them (search metadata exports for the old path).
Confirm repository connection settings (which repo, which user) match the environment where paths were authored.
Verify path normalization: no double slashes, correct leading '/', and case matching the repository tree.
Pin environment variables used in directory paths per environment (dev/qa/prod) so they resolve to existing folders.

When it happens

Trigger: Calling getMetaForEntry with a repository metaPath whose directory portion (everything before the last '/') does not match any directory in the repository tree — e.g. path '/home/admin/myTrans' when '/home/admin' was deleted/renamed, path typed with wrong casing or missing normalization, or referencing a directory in a different repository than the one connected.

Common situations: Repository content reorganized (folders renamed/moved) breaking saved paths; connecting to the wrong repository or a fresh one that lacks the referenced folders; permission-restricted directories invisible to the current user; typos or stale ${VARIABLE} values producing an invalid directory path; Kettle 8+ repository API changes around directory resolution.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/base/MetaFileLoaderImpl.java:390

      if ( isTransMeta() ) {
        throw new KettleException(
          BaseMessages.getString( persistentClass, "JobTrans.Exception.MissingTransFileName" ) );
      } else {
        throw new KettleException(
          BaseMessages.getString( persistentClass, "JobJob.Exception.MissingJobFileName" ) );
      }
    }

    int index = metaPath.lastIndexOf( RepositoryFile.SEPARATOR );
    if ( index != -1 ) {
      realName = metaPath.substring( index + 1 );
      realDirectory = index == 0 ? RepositoryFile.SEPARATOR : metaPath.substring( 0, index );
    }
    realDirectory = r.normalizeSlashes( realDirectory );

    RepositoryDirectoryInterface repositoryDirectory = rep.loadRepositoryDirectoryTree().findDirectory( realDirectory );
    if ( repositoryDirectory == null ) {
      throw new KettleException( "Unable to find repository directory [" + Const.NVL( realDirectory, "" ) + "]" );
    }

    T theMeta = null;
    if ( isTransMeta() ) {
      theMeta = (T) rep.loadTransformation( bowl, realName, repositoryDirectory, null, true, null, tmpSpace );
    } else {
      JobMeta jobMeta = rep.loadJob( realName, repositoryDirectory, null, null, tmpSpace );
      if ( jobMeta != null ) {
        jobMeta.initializeVariablesFrom( tmpSpace );
      }
      theMeta = (T) jobMeta;
    }
    return theMeta;
  }

  private T attemptCacheRead( String realFilename ) {
    if ( !useCache || metaFileCache == null ) {
      return null;

View on GitHub (pinned to f3058517a1)