{"record":{"id":"183f721912c98795","repo":"pentaho/pentaho-kettle","slug":"trans-log-failtoinitializeatleastonestep","errorCode":null,"errorMessage":"Trans.Log.FailToInitializeAtLeastOneStep","messagePattern":"Trans\\.Log\\.FailToInitializeAtLeastOneStep","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/Trans.java","lineNumber":1337,"sourceCode":"\n      // Just for safety, fire the trans finished listeners...\n      try {\n        fireTransFinishedListeners();\n      } catch ( KettleException e ) {\n        // listeners produces errors\n        log.logError( BaseMessages.getString( PKG, \"Trans.FinishListeners.Exception\" ) );\n        // we will not pass this exception up to prepareExecution() entry point.\n      } finally {\n        // Flag the transformation as finished even if exception was thrown\n        setFinished( true );\n      }\n\n      // Pass along the log during preview. Otherwise it becomes hard to see\n      // what went wrong.\n      //\n      if ( preview ) {\n        String logText = KettleLogStore.getAppender().getBuffer( getLogChannelId(), true ).toString();\n        throw new KettleException( BaseMessages.getString( PKG, \"Trans.Log.FailToInitializeAtLeastOneStep\" ) + Const.CR\n          + logText );\n      } else {\n        throw new KettleException( BaseMessages.getString( PKG, \"Trans.Log.FailToInitializeAtLeastOneStep\" )\n          + Const.CR );\n      }\n    }\n\n    log.snap( Metrics.METRIC_TRANSFORMATION_INIT_STOP );\n\n    KettleEnvironment.setExecutionInformation( this, repository );\n\n    setReadyToStart( true );\n  }\n\n  @SuppressWarnings ( \"deprecation\" )\n  private void checkCompatibility() {\n    // If we don't have a previous result and transMeta does have one, someone has been using a deprecated method.\n    //","sourceCodeStart":1319,"sourceCodeEnd":1355,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/Trans.java#L1319-L1355","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the appended log text in the exception to identify the failing step and its init error","Fix the failing step's configuration (connection, credentials, resource paths)","Verify database drivers (JDBC jars) are in lib/ or the plugin's classpath"],"exampleFix":"// before: TableInput step init fails due to bad connection\n// after: fix database connection in the step\nDatabaseMeta db = new DatabaseMeta(\"db\", \"POSTGRESQL\", \"Native\", \"host\", \"mydb\", \"5432\", \"user\", \"pass\");\ntransMeta.addDatabase(db);","handlingStrategy":"try-catch","validationCode":"// pre-flight: test each step's resources before preview\nfor (StepMeta sm : transMeta.getSteps()) {\n  if (!sm.getStepMetaInterface().init(stepMetaInterface_dummy...)) { /* report */ }\n}","typeGuard":null,"tryCatchPattern":"try { trans.prepareExecution(); } catch (KettleException e) { System.err.println(e.getMessage()); /* message includes the preview log text pointing at the failing step */ }","preventionTips":["Test database connections before preview","Keep JDBC drivers up to date in lib/","Validate step configuration in Spoon before batch preview runs"],"tags":["kettle","step-initialization","preview"],"backgroundTag":"module-init-failed","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}