pentaho/pentaho-kettle · error · KettleException

Unable to load directory structure from repository

Error message

Unable to load directory structure from repository

What it means

Failure while loading the children (repository objects) of a directory in the PUR repository: any exception during traversal of the folder's files and construction of EERepositoryObject entries is wrapped as this KettleException. It means the directory structure could not be materialized from the enterprise repository.

Solutions

  1. Inspect the wrapped cause to identify which child file failed to load.
  2. Refresh/reconnect the repository connection and retry loading the tree.
  3. Check server logs for metadata corruption on the affected folder.
  4. Repair or remove the offending repository object via the BA server admin tools.

Example fix

// before
RepositoryDirectoryInterface tree = repo.loadRepositoryDirectoryTree();
// after
try {
  RepositoryDirectoryInterface tree = repo.loadRepositoryDirectoryTree();
} catch (KettleException e) {
  log.error("Tree load failed: {}", e.getCause(), e);
  throw e;
}
Defensive patterns

Strategy: retry

Validate before calling

if (!repo.isConnected()) repo.connect(user, pass);
ObjectId dirId = repo.getRepositoryDirectoryTree().findDirectory(path).getObjectId();
if (dirId == null) throw new KettleException("Directory missing: " + path);

Type guard

null

Try / catch

try {
  tree = repo.loadRepositoryDirectoryTree();
} catch (KettleException e) {
  log.error("Cause: {}", e.getCause());
  throw e;
}

Prevention

When it happens

Trigger: Directory-tree loading code that calls the repository's folder-loading routine (as used by getRepositoryDirectory tree building); any exception listing children or building EERepositoryObject (bad metadata, unsupported object type, server error) triggers it.

Common situations: Corrupted or partially deleted repository objects; server returning unexpected file metadata; permission issues reading a subfolder; stale repository cache after server upgrade.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at plugins/pur/core/src/main/java/org/pentaho/di/repository/pur/PurRepository.java:820

      if ( children != null ) {
        for ( RepositoryFileTree child : children ) {
          if ( child.getFile().isFolder() ) {
            RepositoryDirectory dir = new RepositoryDirectory( parentDir, child.getFile().getName() );
            dir.setObjectId( new StringObjectId( child.getFile().getId().toString() ) );
            parentDir.addSubdirectory( dir );
            fillRepositoryDirectoryFromTree( dir, child );
          } else {
            // a real file, like a Transformation or Job
            RepositoryLock lock = unifiedRepositoryLockService.getLock( child.getFile() );
            RepositoryObjectType objectType = getObjectType( child.getFile().getName() );

            fileChildren.add( new EERepositoryObject( child, parentDir, null, objectType, null, lock, false ) );
          }
        }
        parentDir.setRepositoryObjects( fileChildren );
      }
    } catch ( Exception e ) {
      throw new KettleException( "Unable to load directory structure from repository", e );
    }
  }

  @Override
  public String[] getDirectoryNames( final ObjectId idDirectory ) throws KettleException {
    try {
      readWriteLock.readLock().lock();
      List<RepositoryFile> children;
      try {
        children = pur.getChildren( idDirectory.getId() );
      } finally {
        readWriteLock.readLock().unlock();
      }

      List<String> childNames = new ArrayList<String>();
      for ( RepositoryFile child : children ) {
        if ( child.isFolder() ) {
          childNames.add( child.getName() );

View on GitHub (pinned to f3058517a1)