pentaho/pentaho-kettle · error · KettleException

Unable to load transformation

Error message

Unable to load transformation [{transName}]

What it means

For specification method REPOSITORY_BY_NAME, MetaInjectMeta looks up the transformation's repository directory and calls rep.loadTransformation(realTransname, repdir, ...). Any exception loading it is wrapped in a KettleException with this message naming the transformation. The injection target could not be fetched from the repository.

Solutions

  1. Confirm the transformation name and directory exist in the connected repository.
  2. Verify the repository connection is valid and the user can read the object.
  3. Check that ${Internal.Transformation.Filename.Directory} or the configured directory variable resolves to the intended folder.
  4. Alternatively switch specification to 'by reference' to avoid name-based lookups.

Example fix

// before: hardcoded directory after a repo reorg
String dir = "/prod/etl";
// after: use the current transformation's directory
String dir = "${Internal.Transformation.Filename.Directory}";
Defensive patterns

Strategy: validation

Validate before calling

// Confirm the transformation exists in the repository before loading
ObjectId dirId = rep.getDirectoryID(realDirectory);
if (dirId == null) throw new IllegalStateException("Directory missing: " + realDirectory);
ObjectId trId = rep.getTransformationID(realTransname, dirId);
if (trId == null) throw new IllegalStateException("Transformation missing: " + realTransname);

Try / catch

try {
  mappingTransMeta = rep.loadTransformation(realTransname, repdir, null, true, null);
} catch (KettleException e) {
  logError("Repository load of " + realTransname + " failed: " + e.getCause(), e);
}

Prevention

When it happens

Trigger: loadTransformation with REPOSITORY_BY_NAME where the named transformation does not exist in realDirectory, the repository is unreachable, or loadTransformation throws (permissions, corrupt object).

Common situations: Transformation renamed or moved to another repository folder; connecting to the wrong repository; directory variables (${Internal....}) resolving incorrectly; repository login lacks read permission.

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/30dc079324731cbd. Report an issue: GitHub.

Appendix: source

Thrown at plugins/meta-inject/impl/src/main/java/org/pentaho/di/trans/steps/metainject/MetaInjectMeta.java:584

      case REPOSITORY_BY_NAME:
        String realTransname = tmpSpace.environmentSubstitute( injectMeta.getTransName() );
        String realDirectory = tmpSpace.environmentSubstitute( injectMeta.getDirectoryPath() );
        if ( rep != null ) {
          if ( !Utils.isEmpty( realTransname ) && !Utils.isEmpty( realDirectory ) && rep != null ) {
            RepositoryDirectoryInterface repdir = rep.findDirectory( realDirectory );
            if ( repdir != null ) {
              try {
                // reads the last revision in the repository...
                //
                // TODO: FIXME: see if we need to pass external MetaStore references to the repository?
                //
                mappingTransMeta = rep.loadTransformation( realTransname, repdir, null, true, null );

                mappingTransMeta.getLogChannel().logDetailed( "Loading Mapping from repository",
                  "Mapping transformation [" + realTransname + "] was loaded from the repository" );
              } catch ( Exception e ) {
                throw new KettleException( "Unable to load transformation [" + realTransname + "]", e );
              }
            } else {
              throw new KettleException( BaseMessages.getString( PKG,
                "MetaInjectMeta.Exception.UnableToLoadTransformationFromRepository", realTransname, realDirectory ) );
            }
          }
        } else {
          try {
            mappingTransMeta =
              new TransMeta( bowl, realDirectory + "/" + realTransname, metaStore, rep, true, tmpSpace, null );
          } catch ( KettleException ke ) {
            try {
              // add .ktr extension and try again
              mappingTransMeta =
                new TransMeta( bowl, realDirectory + "/" + realTransname + "." + Const.STRING_TRANS_DEFAULT_EXT,
                  metaStore, rep, true, tmpSpace, null );
            } catch ( KettleException ke2 ) {
              throw new KettleException( BaseMessages.getString( PKG, "StepWithMappingMeta.Exception.UnableToLoadTrans",

View on GitHub (pinned to f3058517a1)