pentaho/pentaho-kettle · error · KettleException

PurRepository.ERROR_0006_UNABLE_TO_RENAME_TRANS

PurRepository.ERROR_0006_UNABLE_TO_RENAME_TRANS

Error message

Unable to rename Transformation from "{0}" to "{1}". Transformation with name "{1}" already exists.

What it means

Thrown by PurRepository.renameTransformation when the target name for a Transformation already exists in the repository. Same mechanism as the Job rename: existence check fails and ERROR_0006_UNABLE_TO_RENAME_TRANS is raised as a KettleException.

Solutions

Pick a unique transformation name for the target folder
Check repository.exists(nameAbstractTransformation, dir) before renaming
Catch the exception and append a suffix/version to the name automatically

Example fix

// before
repository.renameTransformation(transMeta, "extract", dir, "rename");
// after
if (repository.exists(nameAbstractTransformation, dir)) {
  name = "extract_" + System.currentTimeMillis();
}
repository.renameTransformation(transMeta, name, dir, "rename");

Defensive patterns

Strategy: validation

Validate before calling

if (repository.exists(nameAbstractTransformation, targetDir)) {
  throw new IllegalArgumentException("Transformation name already taken in " + targetDir);
}

Try / catch

try {
  repository.renameTransformation(transMeta, newName, dir, comments);
} catch (KettleException e) {
  if (String.valueOf(e.getMessage()).contains("already exists")) {
    // append suffix and retry
  }
}

Prevention

Check existence before renaming
Auto-suffix colliding names
Coordinate renames across teams to avoid conflicts

When it happens

Trigger: Calling PurRepository.renameTransformation(transMeta, name, directory, comments) with a newTitle that matches an existing Transformation in the target folder.

Common situations: Renaming a .ktr in Spoon to a name taken by another transformation; automation scripts that regenerate names; git-like workflows where two users renamed different objects to the same name.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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

Appendix: source

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

      // get file from destination path, should be null for rename goal
      fileFromDestination = pur.getFile( absPath );

      if ( fileFromDestination == null ) {
        file = builder.build();
        NodeRepositoryFileData data;
        data = pur.getDataAtVersionForRead( file.getId(), null, NodeRepositoryFileData.class );

        if ( newTitle != null ) {
          // update file's content only if the title should be changed
          // as this action creates another revision
          pur.updateFile( file, data, versionComment );
        }
        pur.moveFile( idObject.getId(), absPath, null );

        rootRef.clearRef();
        return idObject;
      } else {
        throw new KettleException( BaseMessages.getString( PKG, errorMsgKey, file.getName(), newTitle ) );
      }
    } finally {
      readWriteLock.writeLock().unlock();
    }
  }

  protected String getParentPath( final String path ) {
    if ( path == null ) {
      throw new IllegalArgumentException();
    } else if ( RepositoryFile.SEPARATOR.equals( path ) ) {
      return null;
    }
    int lastSlashIndex = path.lastIndexOf( RepositoryFile.SEPARATOR );
    if ( lastSlashIndex == 0 ) {
      return RepositoryFile.SEPARATOR;
    } else if ( lastSlashIndex > 0 ) {
      return path.substring( 0, lastSlashIndex );
    } else {

View on GitHub (pinned to f3058517a1)