pentaho/pentaho-kettle · error · KettleException

Trans.Exception.UnableToWriteStepInformationToLogTable

Error message

Trans.Exception.UnableToWriteStepInformationToLogTable

What it means

Thrown by Trans.writeStepLogInformation() when writing one start record per transformation step (via db.writeLogRecord(stepLogTable, LogStatus.START, combi, null)) to the configured step log table fails, or when subsequent cleanupLogRecords() fails. Any Exception is wrapped in this message.

Solutions

  1. Check the cause for the failing SQL and restore the step log table database (connection, schema, privileges).
  2. Recreate the step log table from the Log tab generated DDL.
  3. Grant INSERT/DELETE on the step log table to the log user.
  4. Remove the Step log table configuration if per-step start logging is not needed.

Example fix

// before: step_log table absent
KettleException: UnableToWriteStepInformationToLogTable
// after: CREATE TABLE step_log (...); via Log tab SQL generation
Defensive patterns

Strategy: validation

Validate before calling

// Verify step log table exists and the DB accepts writes before execution
Database db = new Database(trans, stepLogTable.getDatabaseMeta());
db.connect();
if (!db.checkTableExists("STEP_LOG")) throw new IllegalStateException("STEP_LOG missing");

Try / catch

try {
  trans.waitUntilFinished();
} catch (KettleException e) {
  log.error("Step start-record logging failed: " + e.getCause().getMessage());
  // re-create table or disable step logging, then re-run
}

Prevention

When it happens

Trigger: writeStepLogInformation() iterates getSteps() and writes a START log row per StepMetaDataCombi into the step log table; a DB error on any write or on cleanupLogRecords(stepLogTable, getName()) triggers this exception.

Common situations: Step log table missing/renamed after migration; one step's metadata can't be serialized to the log columns; DB outage at transformation start; insufficient insert privileges.

Related errors

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

Appendix: source

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

   *
   * @throws KettleException if any errors occur during logging
   */
  protected void writeStepLogInformation() throws KettleException {
    Database db = null;
    StepLogTable stepLogTable = getTransMeta().getStepLogTable();
    try {
      db = createDataBase( stepLogTable.getDatabaseMeta() );
      db.shareVariablesWith( this );
      db.connect();
      db.setCommit( logCommitSize );

      for ( StepMetaDataCombi combi : getSteps() ) {
        db.writeLogRecord( stepLogTable, LogStatus.START, combi, null );
      }

      db.cleanupLogRecords( stepLogTable, getName() );
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG,
        "Trans.Exception.UnableToWriteStepInformationToLogTable" ), e );
    } finally {
      disconnectDb( db );
    }

  }

  protected Database createDataBase( DatabaseMeta meta ) {
    return new Database( this, meta );
  }

  protected synchronized void writeMetricsInformation() throws KettleException {
    Preconditions.checkNotNull( log );
    List<MetricsDuration> metricsList =
      MetricsUtil.getDuration( log.getLogChannelId(), Metrics.METRIC_PLUGIN_REGISTRY_REGISTER_EXTENSIONS_START );
    if ( ( log.isDebug() ) && !metricsList.isEmpty() ) {
      log.logDebug( metricsList.get( 0 ).toString() );
    }

View on GitHub (pinned to f3058517a1)