pentaho/pentaho-kettle · error · KettleException

Trans.Log.FailToInitializeAtLeastOneStep

Error message

Trans.Log.FailToInitializeAtLeastOneStep

What it means

After initializing all steps, if at least one step's init() returned false, Trans throws this KettleException. In preview mode the thrown message additionally appends the captured log buffer so the user can see which step failed to initialize and why.

Solutions

1. Read the appended log text in the exception to identify the failing step and its init error
2. Fix the failing step's configuration (connection, credentials, resource paths)
3. Verify database drivers (JDBC jars) are in lib/ or the plugin's classpath

Example fix

// before: TableInput step init fails due to bad connection
// after: fix database connection in the step
DatabaseMeta db = new DatabaseMeta("db", "POSTGRESQL", "Native", "host", "mydb", "5432", "user", "pass");
transMeta.addDatabase(db);

// pre-flight: test each step's resources before preview
for (StepMeta sm : transMeta.getSteps()) {
  if (!sm.getStepMetaInterface().init(stepMetaInterface_dummy...)) { /* report */ }
}

try { trans.prepareExecution(); } catch (KettleException e) { System.err.println(e.getMessage()); /* message includes the preview log text pointing at the failing step */ }

When it happens

Trigger: trans.prepareExecution/init() where one or more steps return false from their init() method — e.g. database connection failure in a table input step, invalid step settings checked at init time. This specific throw occurs when preview=true.

Common situations: Running a preview in Spoon with a step that can't connect to its database or resource; missing driver; invalid step configuration detected during initialization.

Related errors

• All fields must have an output type to do the preview
• A connection of type PALO is expected
• A connection of type PALO is expected
• A deadlock was detected between steps
• A server socket allocation always has to accompanied by a…

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/Trans.java:1337

      // Just for safety, fire the trans finished listeners...
      try {
        fireTransFinishedListeners();
      } catch ( KettleException e ) {
        // listeners produces errors
        log.logError( BaseMessages.getString( PKG, "Trans.FinishListeners.Exception" ) );
        // we will not pass this exception up to prepareExecution() entry point.
      } finally {
        // Flag the transformation as finished even if exception was thrown
        setFinished( true );
      }

      // Pass along the log during preview. Otherwise it becomes hard to see
      // what went wrong.
      //
      if ( preview ) {
        String logText = KettleLogStore.getAppender().getBuffer( getLogChannelId(), true ).toString();
        throw new KettleException( BaseMessages.getString( PKG, "Trans.Log.FailToInitializeAtLeastOneStep" ) + Const.CR
          + logText );
      } else {
        throw new KettleException( BaseMessages.getString( PKG, "Trans.Log.FailToInitializeAtLeastOneStep" )
          + Const.CR );
      }
    }

    log.snap( Metrics.METRIC_TRANSFORMATION_INIT_STOP );

    KettleEnvironment.setExecutionInformation( this, repository );

    setReadyToStart( true );
  }

  @SuppressWarnings ( "deprecation" )
  private void checkCompatibility() {
    // If we don't have a previous result and transMeta does have one, someone has been using a deprecated method.
    //

View on GitHub (pinned to f3058517a1)