pentaho/pentaho-kettle · error · KettleException

Unexpected error occurred while launching entry

Error message

Unexpected error occurred while launching entry [{0}]

What it means

Wraps any Throwable escaping the recursive execute() of a next job entry. When Job.execute launches a following job entry and it throws unexpectedly (not a normal result failure but a Java exception), the stack is logged and rethrown as a KettleException naming the entry.

Solutions

  1. Read the logged stack tracker (Const.getStackTracker) to identify the root cause in the named entry
  2. Fix or update the failing job entry plugin
  3. Wrap custom job entry code to convert expected failures into a Result with error flag instead of throwing
  4. Check classpath/plugin jars for version conflicts

Example fix

// before
public Result execute(Result r) { return doWork(r); } // throws NPE
// after
public Result execute(Result r) { try { return doWork(r); } catch (Exception e) { r.setErrors(1); logError(...); return r; } }
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check plugin availability
Class<?> entryClass;
try { entryClass = Class.forName(jobEntryPluginClass); } catch (ClassNotFoundException e) {
  throw new IllegalStateException("Job entry plugin class missing: " + jobEntryPluginClass);
}

Try / catch

try {
  job.run();
} catch (KettleException e) {
  if (e.getMessage().startsWith("Unexpected error occurred while launching entry")) {
    Throwable root = e.getCause();
    log.error("Entry failed with root cause", root);
    result.setErrors(1);
  }
}

Prevention

When it happens

Trigger: A job entry's run/execute method throws a Throwable (e.g. NPE, ClassCastException, missing class) during nested execution of the next entry in the job flow.

Common situations: Buggy custom job entry plugins; environment issues inside an entry (missing files, DB down) that surface as unchecked exceptions; version mismatch of plugin dependencies causing NoClassDefFoundError.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/job/Job.java:875

                threadResult.setNrErrors( 1L );
                threadResults.add( threadResult );
              }
            }
          };
          Thread thread = new Thread( runnable );
          threads.add( thread );
          thread.start();
          if ( log.isBasic() ) {
            log.logBasic( BaseMessages.getString( PKG, "Job.Log.LaunchedJobEntryInParallel", nextEntry.getName() ) );
          }
        } else {
          try {
            // Same as before: blocks until it's done
            //
            res = execute( nr + 1, newResult, nextEntry, jobEntryCopy, nextComment );
          } catch ( Throwable e ) {
            log.logError( Const.getStackTracker( e ) );
            throw new KettleException( BaseMessages.getString( PKG, "Job.Log.UnexpectedError", nextEntry.toString() ),
                e );
          }
          if ( log.isBasic() ) {
            log.logBasic( BaseMessages.getString( PKG, "Job.Log.FinishedJobEntry", nextEntry.getName(), res.getResult()
                + "" ) );
          }
        }
      }
    }

    // OK, if we run in parallel, we need to wait for all the job entries to
    // finish...
    //
    if ( jobEntryCopy.isLaunchingInParallel() ) {
      for ( int i = 0; i < threads.size(); i++ ) {
        Thread thread = threads.get( i );
        JobEntryCopy nextEntry = threadEntries.get( i );

View on GitHub (pinned to f3058517a1)