pentaho/pentaho-kettle · error · KettleException

Unable to rename the specified repository directory [dir]

Error message

Unable to rename the specified repository directory [dir]

What it means

Wrapper KettleException from the deprecated renameRepositoryDirectory(RepositoryDirectory) method, thrown when the internal renameDirectory call fails for any reason. Since it passes a null parent id, it performs a name-only rename; all validation failures from renameDirectory (self-parent, descendant cycle, duplicate name) or DB errors surface wrapped here.

Solutions

  1. Inspect e.getCause() to distinguish validation failure vs database failure
  2. Migrate to the non-deprecated renameRepositoryDirectory(ObjectId, RepositoryDirectoryInterface, String)
  3. Verify the directory still exists and the new name is unique among siblings before renaming
  4. Check repository connectivity if the cause is a KettleDatabaseException

Example fix

// before
repository.renameRepositoryDirectory( dir ); // deprecated
// after
repository.renameRepositoryDirectory( dir.getObjectId(), dir.getParent(), "NewName" );
Defensive patterns

Strategy: try-catch

Validate before calling

// avoid the deprecated overload entirely; use:
// repository.renameRepositoryDirectory( dir.getObjectId(), dir.getParent(), newName );

Try / catch

try {
  repository.renameRepositoryDirectory( dir );
} catch ( KettleException e ) {
  Throwable cause = e.getCause();
  // duplicate-name vs database failure: branch on cause/message
}

Prevention

When it happens

Trigger: Calling repository.renameRepositoryDirectory(dir) (deprecated overload) when: the new name collides with a sibling, the directory ObjectId is stale/missing, or the database update/commit fails.

Common situations: Legacy code still using the deprecated overload after upgrading Pentaho/Kettle; renaming a directory that was deleted by another client; name conflicts in shared repositories.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/kdr/delegates/KettleDatabaseRepositoryDirectoryDelegate.java:342

    } catch ( Exception e ) {
      throw new KettleException( "Unexpected error deleting repository directory:", e );
    }
  }

  /**
   * @deprecated use {@link #renameRepositoryDirectory(ObjectId, RepositoryDirectoryInterface, String)}
   *
   * @param dir
   * @return
   * @throws KettleException
   */
  @Deprecated
  public ObjectId renameRepositoryDirectory( RepositoryDirectory dir ) throws KettleException {
    try {
      renameDirectory( dir.getObjectId(), null, dir.getName() );
      return dir.getObjectId(); // doesn't change in this specific case.
    } catch ( Exception e ) {
      throw new KettleException( "Unable to rename the specified repository directory [" + dir + "]", e );
    }
  }

  public ObjectId renameRepositoryDirectory( ObjectId id, RepositoryDirectoryInterface newParentDir, String newName ) throws KettleException {
    ObjectId parentId = null;
    if ( newParentDir != null ) {
      parentId = newParentDir.getObjectId();
    }

    try {
      renameDirectory( id, parentId, newName );
      return id; // doesn't change in this specific case.
    } catch ( Exception e ) {
      throw new KettleException( "Unable to rename the specified repository directory [" + id + "]", e );
    }
  }

  /**

View on GitHub (pinned to f3058517a1)