pentaho/pentaho-kettle · error · KettleException

Unable to rename the specified repository directory [id]

Error message

Unable to rename the specified repository directory [id]

What it means

Wrapper KettleException from renameRepositoryDirectory(ObjectId, RepositoryDirectoryInterface, String), thrown when renameDirectory(id, parentId, newName) fails. The wrap message includes the ObjectId. All pre-checks in renameDirectory (self-parent, descendant cycle, duplicate child name) and database failures during the update surface here wrapped as the cause.

Solutions

  1. Validate before calling: new parent is not the directory itself and not inside its subtree
  2. Ensure the target name is unique in the destination (findChild check)
  3. Refresh the directory tree to obtain fresh ObjectIds if the tree changed concurrently
  4. Inspect e.getCause() for database errors and fix connectivity/constraints

Example fix

// before
repo.renameRepositoryDirectory( id, newParent, name );
// after
if ( !id.equals( newParent.getObjectId() ) && newParent.findChild( name ) == null ) {
  repo.renameRepositoryDirectory( id, newParent, name );
} else {
  log.warn( "Invalid move: self-parent or name conflict" );
}
Defensive patterns

Strategy: validation

Validate before calling

ObjectId parentId = newParentDir == null ? null : newParentDir.getObjectId();
if ( parentId != null && ( parentId.equals( id ) || isDescendantOf( newParentDir, id ) ) ) {
  throw new IllegalArgumentException( "Invalid move target" );
}
if ( newName != null && newParentDir != null && newParentDir.findChild( newName ) != null ) {
  throw new IllegalArgumentException( "Name conflict in destination" );
}

Try / catch

try {
  repo.renameRepositoryDirectory( id, newParentDir, newName );
} catch ( KettleException e ) {
  // branch on cause: validation message vs KettleDatabaseException
}

Prevention

When it happens

Trigger: repository.renameRepositoryDirectory(id, newParentDir, newName) where id equals the new parent id, the new parent is a descendant of id, the destination already has a child named newName, or the database update/commit fails.

Common situations: Programmatic reorganization scripts moving folders into their own subtrees; concurrent renames causing name collisions; stale ObjectIds from an outdated directory tree snapshot; DB connectivity problems.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

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

    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 );
    }
  }

  /**
   * Create a new directory, possibly by creating several sub-directies of / at the same time.
   *
   * @param parentDirectory
   *          the parent directory
   * @param directoryPath
   *          The path to the new Repository Directory, to be created.
   * @return The created sub-directory
   * @throws KettleException
   *           In case something goes wrong
   */
  public RepositoryDirectoryInterface createRepositoryDirectory( RepositoryDirectoryInterface parentDirectory,
    String directoryPath ) throws KettleException {

    // RepositoryDirectoryInterface refreshedParentDir =

View on GitHub (pinned to f3058517a1)