pentaho/pentaho-kettle · critical · KettleTransException

Trans.Exception.ErrorWritingLogRecordToTable

Error message

Trans.Exception.ErrorWritingLogRecordToTable

What it means

Thrown by Trans.beginProcessing() when writing the initial transformation log record to the transformation log table fails with a KettleException. This is the very first logging write during startup (when interval logging is configured a timer is also set up), so failure here aborts the transformation before any step runs.

Solutions

  1. Inspect the cause for the root SQL/connection error and fix the transformation log database first.
  2. Verify the transformation log table exists with the expected schema; regenerate it from the Log tab 'SQL' button.
  3. Test the database connection and credentials used by the transformation log table.
  4. Check DB server logs for connection limits or quota issues if the cause shows resource exhaustion.

Example fix

// before: log table dropped after DB migration
KettleTransException: ErrorWritingLogRecordToTable [trans_log]
// after: recreate trans_log (Log tab SQL) or point the log table at a live connection
Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight: connect to the trans log DB and confirm the table before execution
DatabaseMeta meta = transMeta.getTransLogTable().getDatabaseMeta();
Database db = new Database(trans, meta);
db.connect();
if (!db.checkTableExists("TRANS_LOG")) throw new IllegalStateException("TRANS_LOG missing");
db.disconnect();

Try / catch

try {
  trans.execute(null);
} catch (KettleTransException e) {
  log.error("Cannot start transformation: initial log record write failed", e.getCause());
  alertOps(); // startup aborts before any step runs
}

Prevention

When it happens

Trigger: beginProcessing() writes the start log record via the transLogTableDatabaseConnection; any KettleException (connection failure, SQL error, missing table) is rethrown as KettleTransException(ErrorWritingLogRecordToTable, logTable).

Common situations: Wrong log database connection credentials; transformation log table does not exist; database max connections exhausted; network unreachable at startup; log table columns altered after a PDI upgrade.

Related errors

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

Appendix: source

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

                  "Trans.Exception.UnableToPerformIntervalPerformanceLogging" ), e );
                // Also stop the show...
                //
                errors.incrementAndGet();
                stopAll();
              }
            }
          };
          timer.schedule( timerTask, perfLogInterval * 1000, perfLogInterval * 1000 );

          addTransListener( new TransAdapter() {
            @Override
            public void transFinished( Trans trans ) {
              timer.cancel();
            }
          } );
        }
      } catch ( KettleException e ) {
        throw new KettleTransException( BaseMessages.getString( PKG, "Trans.Exception.ErrorWritingLogRecordToTable",
          logTable ), e );
      } finally {
        // If we use interval logging, we keep the connection open for performance reasons...
        //
        if ( transLogTableDatabaseConnection != null && ( intervalInSeconds <= 0 ) ) {
          transLogTableDatabaseConnection.disconnect();
          transLogTableDatabaseConnection = null;
        }
      }
    } catch ( KettleException e ) {
      throw new KettleTransException( BaseMessages.getString( PKG,
        "Trans.Exception.UnableToBeginProcessingTransformation" ), e );
    }
  }

  /**
   * Writes log channel information to a channel logging table (if one has been configured).
   *

View on GitHub (pinned to f3058517a1)