What causes "JobExecutorMeta.Exception.UnableToLoadJob" in pentaho/pentaho-kettle?

Inspect e.getCause() for the real load failure and fix it (missing file, repository error, XML parse issue).

pentaho/pentaho-kettle · error · KettleException

JobExecutorMeta.Exception.UnableToLoadJob

Error message

JobExecutorMeta.Exception.UnableToLoadJob

What it means

Wrapping KettleException thrown by MetaFileLoaderImpl.getMetaForStep: when loading a child job (JobMeta branch, e.g. a Job Executor step) from repository or XML fails with any exception, it is rethrown with the JobExecutorMeta 'unable to load job' message and the original exception as cause. It is the job counterpart of error 618; diagnose via the wrapped cause.

Solutions

Inspect e.getCause() for the real load failure and fix it (missing file, repository error, XML parse issue).
Verify the child job path: resolve all variables in the filename and confirm the .kjb exists and is readable at runtime.
Open the child job in Spoon to confirm it loads under the current PDI version; re-save it or install the missing job-entry plugin.
If loading from repository, confirm metaName/directory reference an existing repository object and the user has access.
Check/clear the meta file cache entry if a stale cached artifact may be interfering.

Example fix

// before
JobExecutorMeta jeMeta = new JobExecutorMeta();
jeMeta.setFileName("${JOBS_DIR}/nightly.kjb"); // ${JOBS_DIR} undefined

// after
String real = space.environmentSubstitute("${JOBS_DIR}") + "/nightly.kjb";
if (new File(real).canRead()) {
  jeMeta.setFileName(real);
} else {
  throw new KettleException("Child job not found: " + real);
}

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

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

Prevention

Resolve and verify every ${VARIABLE} in child job filenames before running the parent job.
Deploy child .kjb files with the parent or verify repository paths exist in the target environment.
Install all job-entry plugins referenced by child jobs in the runtime installation.
Inspect e.getCause() first — this error always wraps the underlying load failure.

When it happens

Trigger: specificationMethod=FILENAME load via attemptLoadMeta (new JobMeta(...)) throwing — missing/unreadable .kjb file, corrupt XML, schema incompatibility — or repository load via getMetaFromRepository2 throwing; any Exception in the try block is wrapped by this message.

Common situations: Job Executor entry pointing at a .kjb that was moved/deleted or whose ${VARIABLE} path resolved incorrectly; child job saved with a newer PDI version failing to parse; repository job renamed or directory changed; repository connectivity/permission issues; missing job-entry plugins referenced by the child job.

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

Appendix: source

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

        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 );
          realDirectory = space.environmentSubstitute( realDirectory );
        }

View on GitHub (pinned to f3058517a1)