pentaho/pentaho-kettle · critical · KettleException

Unable to load the directory tree from this file repository

Error message

Unable to load the directory tree from this file repository

What it means

loadRepositoryDirectoryTree() reconstructs the full RepositoryDirectory hierarchy by reading the repository's directory metadata file; any exception during this read/parse is wrapped in this fixed-message KettleException. Since nearly every repository operation depends on the directory tree, this failure typically makes the whole repository unusable until fixed.

Solutions

1. Verify the repository directory metadata file exists in the base folder and is valid XML
2. Restore the directory file from backup if it is truncated or corrupt
3. Fix filesystem permissions or the base-directory configuration
4. Recreate the repository structure (re-save folders from Spoon) if no backup exists

Example fix

// before
RepositoryDirectoryInterface tree = repository.loadRepositoryDirectoryTree();
// after
RepositoryDirectoryInterface tree;
try {
  tree = repository.loadRepositoryDirectoryTree();
} catch (KettleException e) {
  throw new KettleException("Repository unusable: directory tree unreadable — check base dir/metadata file", e);
}

File dirFile = new File(repoBaseDirectory, DIRECTORY_ELEMENTS_FILENAME); // metadata file used by the file repo
if (!dirFile.isFile()) throw new KettleException("Repository directory metadata file missing: " + dirFile);
if (!dirFile.canRead()) throw new KettleException("Repository directory metadata not readable");

try {
  RepositoryDirectoryInterface tree = repository.loadRepositoryDirectoryTree();
} catch (KettleException e) {
  logger.fatal("Repository directory tree unreadable; restore metadata file from backup", e);
  throw new KettleException("Repository unusable — check base directory and metadata file", e);
}

When it happens

Trigger: Calling loadRepositoryDirectoryTree() (directly or via findDirectory/getDirectoryID) when the directory metadata file is missing, unreadable, corrupt, or its XML cannot be parsed into RepositoryDirectory nodes.

Common situations: Wrong base directory configured so the .kdb/.xml directory file is absent; the directory file truncated by an aborted write or disk-full event; permission problems; the repository folder synchronized between machines leaving conflicts.

Related errors

• Unable to get list of transformations in folder with id : +…
• Unable to get list of transformations names in folder with…
• Unable to get root object ids for extension [ + extension +…
• Unable to write log entry to file [ + logfile + ]
• Class [ + repositoryElement.getClass().getName() + ] needs…

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/filerep/KettleFileRepository.java:992

      FileObject folder = KettleVFS.getInstance( DefaultBowl.getInstance() ).getFileObject( folderName );

      for ( FileObject child : folder.getChildren() ) {
        if ( child.getType().equals( FileType.FOLDER ) ) {
          if ( !child.isHidden() || !repositoryMeta.isHidingHiddenFiles() ) {
            if ( !".meta".equals( child.getName().getBaseName() ) ) {
              RepositoryDirectory subDir = new RepositoryDirectory( dir, child.getName().getBaseName() );
              subDir.setObjectId( new StringObjectId( calcObjectId( subDir ) ) );
              dir.addSubdirectory( subDir );

              loadRepositoryDirectoryTree( subDir );
            }
          }
        }
      }

      return dir;
    } catch ( Exception e ) {
      throw new KettleException( "Unable to load the directory tree from this file repository", e );
    }
  }

  @Override
  public RepositoryDirectoryInterface findDirectory( String directory ) throws KettleException {
    return loadRepositoryDirectoryTree().findDirectory( directory );
  }

  @Override
  public RepositoryDirectoryInterface findDirectory( ObjectId directory ) throws KettleException {
    return loadRepositoryDirectoryTree().findDirectory( directory );
  }

  @Override
  public List<RepositoryElementMetaInterface> getTransformationObjects( ObjectId idDirectory,
    boolean includeDeleted ) throws KettleException {

    try {

View on GitHub (pinned to f3058517a1)