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

Inspect the cause chain (e.getCause()) — fix the underlying load error it names (missing file, repository directory, XML parse).

pentaho/pentaho-kettle · error · KettleException

StepWithMappingMeta.Exception.UnableToLoadTrans

Error message

StepWithMappingMeta.Exception.UnableToLoadTrans

What it means

Wrapping KettleException thrown by MetaFileLoaderImpl.getMetaForStep: when loading a child transformation (TransMeta branch, e.g. a Mapping or Transformation Executor step) from repository or XML fails with any exception, it is rethrown with the StepWithMappingMeta 'unable to load transformation' message and the original exception as cause. The real failure (parse error, missing file, repository error) is in the cause chain.

Solutions

Inspect the cause chain (e.getCause()) — fix the underlying load error it names (missing file, repository directory, XML parse).
Verify the child transformation path/file: resolve all ${VARIABLES} in the filename and confirm the .ktr exists and is readable at runtime.
Open the child transformation in Spoon to confirm it parses in the current PDI version; re-save or upgrade/downgrade the plugin producing the error.
If loading from repository, confirm specificationMethod, metaName and directory match an existing repository object (see errors 615-617).
Clear or bypass any stale meta file cache entry (metaFileCache) that may hold a broken reference.

Example fix

// before
String file = "${INTERNAL_TRANSFORM_DIR}/child.ktr"; // variable unset at runtime
mappingMeta.setFileName(file);

// after
String file = space.environmentSubstitute("${INTERNAL_TRANSFORM_DIR}") + "/child.ktr";
if (new File(file).canRead()) {
  mappingMeta.setFileName(file);
} else {
  throw new KettleException("Child transformation not found: " + file);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Java caller, before getMetaForStep for FILENAME-based specs
String real = space.environmentSubstitute(mappingMeta.getFileName());
if (!(new File(real).canRead())) {
  throw new IllegalArgumentException("Child transformation not readable: " + real);
}

Try / catch

try {
  T meta = loader.getMetaForStep(bowl, rep, metaStore, space);
} catch (KettleException e) {
  if (String.valueOf(e.getMessage()).contains("UnableToLoadTrans")) {
    log.error("Failed to load child transformation", e.getCause());
    throw new ConfigurationException("Child transformation load failed; cause: "
      + (e.getCause() != null ? e.getCause().getMessage() : e.getMessage()), e);
  }
  throw e;
}

Prevention

Resolve and verify every ${VARIABLE} in child transformation filenames before running the parent.
Keep child .ktr files in stable, deployed locations alongside the parent (relative paths where possible).
Ensure all step plugins used by child transformations are installed in the runtime's plugin folders.
Check the cause chain first — this error is always a wrapper around the real load failure.

When it happens

Trigger: specificationMethod=FILENAME with rep==null path via attemptLoadMeta (new TransMeta(...)) throwing — corrupt/unreadable .ktr XML, missing file, incompatible schema — or getMetaFromRepository2/getMetaFromRepository throwing for repository loads; any Exception during these load attempts is wrapped by this message.

Common situations: Child transformation file moved/deleted or variable in filename unresolved to a bad path; .ktr saved by a newer PDI version failing to parse; repository directory/object renamed; permission or network problems against the repository; class-not-found for a step plugin used inside the child transformation.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/base/MetaFileLoaderImpl.java:467

          // via parent space.
          realFilename = space.environmentSubstitute( realFilename );
        }
        theMeta = attemptCacheRead( realFilename ); //try to get from the cache first
        if ( theMeta == null ) {
          try {
            // OK, load the meta-data from file...
            // Don't set internal variables: they belong to the parent thread!
            if ( rep != null ) {
              theMeta = getMetaFromRepository2( bowl, realFilename, rep, r, idContainer );
            }
            if ( theMeta == null ) {
              theMeta = attemptLoadMeta( bowl, realFilename, rep, metaStore, null, tmpSpace, idContainer );
              LogChannel.GENERAL.logDetailed( LOADING + friendlyMetaType + FROM_REPOSITORY,
                friendlyMetaType + " was loaded from XML file [" + realFilename + "]" );
            }
          } catch ( Exception e ) {
            if ( isTransMeta() ) {
              throw new KettleException(
                BaseMessages.getString( persistentClass, "StepWithMappingMeta.Exception.UnableToLoadTrans" ), e );
            } else {
              throw new KettleException(
                BaseMessages.getString( persistentClass, "JobExecutorMeta.Exception.UnableToLoadJob" ), e );
            }
          }
        }
        break;

      case REPOSITORY_BY_NAME:
        String realMetaName = tmpSpace.environmentSubstitute( Const.NVL( metaName, "" ) );
        String realDirectory = tmpSpace.environmentSubstitute( Const.NVL( directory, "" ) );

        if ( isTransMeta() && space != null ) {
          // This is a parent transformation and parent variable should work here. A child file name can be
          // resolved via
          // parent space.
          realMetaName = space.environmentSubstitute( realMetaName );

View on GitHub (pinned to f3058517a1)