What causes "MetaInjectMeta.Exception.UnableToLoadTrans" in pentaho/pentaho-kettle?

Check the fileName value in the message and confirm that file exists and is readable.

pentaho/pentaho-kettle · error · KettleException

MetaInjectMeta.Exception.UnableToLoadTrans

MetaInjectMeta.Exception.UnableToLoadTrans

Error message

MetaInjectMeta.Exception.UnableToLoadTrans

What it means

In MetaInjectMeta's filename-encoding/relocation logic (building a new export filename and switching specification to FILENAME), any exception in the surrounding block is rethrown as a KettleException with localized MetaInjectMeta.Exception.UnableToLoadTrans naming the current fileName. It indicates the step could not resolve/normalize its referenced transformation file.

Solutions

Check the fileName value in the message and confirm that file exists and is readable.
Fix or define the variables used in the filename before running the export/load.
Verify write permissions if a new proposed filename must be created in that directory.
Re-point the Meta Inject step at the transformation file explicitly.

Example fix

// before
String file = "${UNDEFINED_VAR}/child.ktr";
// after: ensure variable defined or use internal variable
String file = "${Internal.Transformation.Filename.Directory}/child.ktr";

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate the current fileName resolves before the export/normalize step
String resolved = space.environmentSubstitute(fileName);
if (Utils.isEmpty(resolved)) throw new IllegalStateException("fileName variable unresolved");

Try / catch

try {
  editFileName();
} catch (KettleException e) {
  logError("Unable to load trans referenced by " + fileName + ": " + e.getMessage(), e);
}

Prevention

Define variables used in filenames before exports
Ensure write permission on the export target directory
Avoid relative paths; anchor to internal directory variables

When it happens

Trigger: The load/normalize routine that sets fileName and setSpecificationMethod(FILENAME) hitting an exception — e.g. variable substitution failing, IO errors deriving newFilename, or the referenced file being unreadable.

Common situations: Exporting/moving a job whose Meta Inject steps reference files by relative path; missing variables during export; file permissions on the target directory when proposing a new filename.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

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

      // Set the correct filename inside the XML.
      //
      executorTransMeta.setFilename( newFilename );

      // exports always reside in the root directory, in case we want to turn
      // this into a file repository...
      //
      executorTransMeta.setRepositoryDirectory( new RepositoryDirectory() );

      // change it in the entry
      //
      fileName = newFilename;

      setSpecificationMethod( ObjectLocationSpecificationMethod.FILENAME );

      return proposedNewFilename;
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "MetaInjectMeta.Exception.UnableToLoadTrans",
        fileName ) );
    }
  }

  @Override
  public boolean excludeFromCopyDistributeVerification() {
    return true;
  }

  @Override
  public boolean excludeFromRowLayoutVerification() {
    return true;
  }

  /**
   * @return the sourceStepName
   */
  public String getSourceStepName() {

View on GitHub (pinned to f3058517a1)