pentaho/pentaho-kettle · error · KettleException

Unable to load the job: please specify the name and…

Error message

Unable to load the job: please specify the name and repository directory OR a filename

What it means

In JobEntryJob.execute(), after getJobMeta(rep, this) attempts to load the referenced sub-job, a null result means the entry was configured with no usable source: neither a repository name+directory, nor a repository reference, nor a filename resolved. The entry throws this KettleException because there is nothing to run.

Solutions

Open the Job entry dialog and set either a valid repository job name + directory or a filename
Verify the variables used in the jobname/filename fields resolve at runtime (log environmentSubstitute values)
Ensure the repository connection (rep) is available when the entry is configured as repository-based
If using by-reference, confirm jobObjectId points to an existing repository job

Example fix

// before: relying on a variable that may not resolve
//   Job name: ${SUB_JOB_NAME}
// after: guarantee a default so the name always resolves
//   Job name: ${SUB_JOB_NAME:-monthly_load}  (set variable before the job runs)
setVariable("SUB_JOB_NAME", Const.NVL(getVariable("SUB_JOB_NAME", "monthly_load"), "monthly_load"));

Defensive patterns

Strategy: validation

Validate before calling

JobEntryJob je = (JobEntryJob) jobMeta.findJobEntry(name);
boolean ok = (je.getJobObjectId() != null)
  || (je.getSpecificationMethod() == ObjectLocationSpecificationMethod.REPOSITORY_BY_NAME
      && !Utils.isEmpty(je.getName()) && !Utils.isEmpty(je.getDirectory()))
  || (je.getSpecificationMethod() == ObjectLocationSpecificationMethod.FILENAME
      && !Utils.isEmpty(environmentSubstitute(je.getFilename())));
if (!ok) throw new IllegalArgumentException("Job entry needs a repository name+directory or a filename");

Try / catch

try {
  result = jobEntry.execute(parentResult, nr);
} catch (KettleException e) {
  if (e.getMessage().contains("please specify the name and repository directory OR a filename")) {
    // stop the job: configuration is incomplete, retrying will not help
  }
  throw e;
}

Prevention

Always set either filename or repository job name+directory in the Job entry dialog
Avoid variables in jobname/filename unless they are guaranteed defined at runtime
After copying jobs across environments, re-verify each Job entry's target
Use REPOSITORY_BY_REFERENCE only when the referenced object is known to exist

When it happens

Trigger: Executing the 'Job' job entry when specificationMethod is REPOSITORY_BY_NAME but jobname/directory variables substitute to empty, or FILENAME but the environmentSubstitute'd filename is empty/null, or REPOSITORY_BY_REFERENCE with an invalid jobObjectId — getJobMeta() returns null and execute() throws.

Common situations: Job entry copied to another environment where variables like ${Internal.Job.Filename.Directory} don't resolve; jobname field left blank; repository connection null at runtime so repository-based load silently returns null.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — 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/0f5a2da0f6c1f0bf. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/job/entries/job/JobEntryJob.java:696

          if ( log.isDetailed() ) {
            logDetailed( "Loading job from XML file : [" + environmentSubstitute( filename ) + "]" );
          }
          break;
        case REPOSITORY_BY_REFERENCE:
          if ( log.isDetailed() ) {
            logDetailed( "Loading job from repository by reference : [" + jobObjectId + "]" );
          }
          break;
        default:
          break;
      }

      JobMeta jobMeta = getJobMeta( rep, this );

      // Verify that we loaded something, complain if we did not...
      //
      if ( jobMeta == null ) {
        throw new KettleException(
          "Unable to load the job: please specify the name and repository directory OR a filename" );
      }

      verifyRecursiveExecution( parentJob, jobMeta );

      int iteration = 0;
      String[] args1 = arguments;
      // no arguments? Check the parent jobs arguments
      if ( args1 == null || args1.length == 0 ) {
        args1 = parentJob.getArguments();
      }

      copyVariablesFrom( parentJob );
      setParentVariableSpace( parentJob );

      //
      // For the moment only do variable translation at the start of a job, not
      // for every input row (if that would be switched on)

View on GitHub (pinned to f3058517a1)