pentaho/pentaho-kettle · error · KettleException

StepWithMappingMeta.Exception.UnableToLoadTrans

StepWithMappingMeta.Exception.UnableToLoadTrans

Error message

StepWithMappingMeta.Exception.UnableToLoadTrans

What it means

Fallback path in the REPOSITORY_BY_NAME branch: after the direct repository load fails, MetaInjectMeta tries to load '<directory>/<transname>.ktr' as a file. If that KettleException also fails, it throws with localized StepWithMappingMeta.Exception.UnableToLoadTrans plus the directory, without a cause. Both load strategies have failed.

Solutions

  1. Locate the transformation: confirm its actual repository path or file location.
  2. Fix the directory/transName fields in the Meta Inject step dialog.
  3. Validate the target .ktr opens standalone in Spoon.
  4. Re-select the mapping transformation to reset the specification method cleanly.
Defensive patterns

Strategy: fallback

Validate before calling

// Check both load targets before invoking the step
boolean inRepo = rep.getTransformationID(realTransname, rep.getDirectoryID(realDirectory)) != null;
boolean onDisk = new File(realDirectory + "/" + realTransname + ".ktr").exists();
if (!inRepo && !onDisk) throw new IllegalStateException("Transformation exists nowhere: " + realTransname);

Try / catch

try {
  loadByName();
} catch (KettleException e) {
  try {
    loadAsFile();
  } catch (KettleException e2) {
    logError("Neither repository nor file load worked for " + realTransname, e2);
  }
}

Prevention

When it happens

Trigger: loadTransformation where rep.loadTransformation threw and the secondary new TransMeta(realDirectory + "/" + realTransname + ".ktr") also threw KettleException (file missing/corrupt).

Common situations: Transformation genuinely absent from both repository and filesystem; renaming the .ktr file extension or moving files out of the repo-mapped directory; corrupt transformation XML.

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/465dbb2cab2d779f. Report an issue: GitHub.

Appendix: source

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

                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",
                realTransname ) + realDirectory );
            }
          }
        }
        break;
      case REPOSITORY_BY_REFERENCE:
        // Read the last revision by reference...
        mappingTransMeta = rep.loadTransformation( injectMeta.getTransObjectId(), null );
        break;
      default:
        break;
    }

    // Pass some important information to the mapping transformation metadata:
    //
    mappingTransMeta.copyVariablesFrom( space );
    mappingTransMeta.setRepository( rep );
    mappingTransMeta.setFilename( mappingTransMeta.getFilename() );

View on GitHub (pinned to f3058517a1)