pentaho/pentaho-kettle · error · KettleException

Trans.Exception.UnableToLoadTransformation

Error message

Trans.Exception.UnableToLoadTransformation

What it means

This Trans constructor loads the transformation metadata from a repository by name and directory, or from a filename. If the repository directory lookup fails (rep.findDirectory returns null), it throws this KettleException because the transformation cannot be loaded from the given location.

Solutions

  1. Verify the repository directory (dirname) exists and the transformation name is correct
  2. Browse the repository in Spoon to find the actual directory path and update the caller
  3. If loading by filename, confirm the file exists and is a valid KTR

Example fix

// before
new Trans(repository, "myTrans", "/old/path");
// after
new Trans(repository, "myTrans", "/prod/transforms"); // existing directory
Defensive patterns

Strategy: try-catch

Validate before calling

RepositoryDirectoryInterface dir = rep.findDirectory(dirname);
if (dir == null || rep.exists(name, dir, RepositoryObjectType.TRANSFORMATION)) throw new IllegalStateException("Transformation not found: " + dirname + "/" + name);

Try / catch

try { Trans t = new Trans(rep, name, dirname); } catch (KettleException e) { log.error("Cannot load trans " + name + " from " + dirname, e); }

Prevention

When it happens

Trigger: new Trans(rep, name, dirname) where the directory does not exist in the repository; or the filename branch failing to construct a TransMeta.

Common situations: Hardcoded repository paths that don't exist after repository restructuring; wrong dirname variable value; migrating transformations between repositories; missing KTR file at the given filename.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/Trans.java:754

    this( bowl, parent, rep, name, dirname, filename, null);
  }

  @Deprecated
  public <Parent extends VariableSpace & NamedParams> Trans( Parent parent, Repository rep, String name, String dirname,
      String filename, TransMeta parentTransMeta ) throws KettleException {
      this( DefaultBowl.getInstance(), parent, rep, name, dirname, filename, parentTransMeta );
  }

  public <Parent extends VariableSpace & NamedParams> Trans( Bowl bowl, Parent parent, Repository rep, String name,
      String dirname, String filename, TransMeta parentTransMeta ) throws KettleException {
    this();
    try {
      if ( rep != null ) {
        RepositoryDirectoryInterface repdir = rep.findDirectory( dirname );
        if ( repdir != null ) {
          this.transMeta = rep.loadTransformation( name, repdir, null, false, null ); // reads last version
        } else {
          throw new KettleException( BaseMessages.getString( PKG, "Trans.Exception.UnableToLoadTransformation", name,
            dirname ) );
        }
      } else {
        transMeta = parentTransMeta != null ? parentTransMeta : new TransMeta( bowl, filename,
          false );
      }

      this.log = new LogChannel( LogChannel.GENERAL_SUBJECT, false, false );
      this.log.setHooks( this );

      transMeta.initializeVariablesFrom( parent );
      initializeVariablesFrom( parent );
      // PDI-3064 do not erase parameters from meta!
      // instead of this - copy parameters to actual transformation
      this.copyParametersFrom( parent );
      this.activateParameters();

      this.setDefaultLogCommitSize();

View on GitHub (pinned to f3058517a1)