pentaho/pentaho-kettle · critical · KettleTransException

Trans.Exception.UnableToBeginProcessingTransformation

Error message

Trans.Exception.UnableToBeginProcessingTransformation

What it means

The outermost wrapper of Trans.beginProcessing(): any KettleException raised while preparing transformation logging at startup (initial log record, dependent date range, timer setup, and inner KettleTransExceptions like ConnectionCouldNotBeFound) is rethrown as UnableToBeginProcessingTransformation. It means the transformation could not start its logging subsystem and therefore never begins execution.

Solutions

Walk the cause chain down to the root KettleException (e.g. ConnectionCouldNotBeFound, ErrorWritingLogRecordToTable) and fix that specific issue.
Test every database connection configured in the transformation's Log tab.
Recreate all configured log tables to match the current PDI version's expected schema.
Compare transformation XML against the target environment's connection list after migrations.

Example fix

// before: transformation starts without any log database reachable
KettleTransException: UnableToBeginProcessingTransformation
// after: start DB, test connection in Log tab, then relaunch transformation

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight all log table connections configured on the transformation
for (LogTableInterface lt : List.of(transMeta.getTransLogTable(), transMeta.getChannelLogTable(), transMeta.getStepLogTable(), transMeta.getMetricsLogTable())) {
  DatabaseMeta dm = lt.getDatabaseMeta();
  if (dm != null && (dm.getID() == null)) throw new IllegalStateException("Unresolved log connection: " + dm.getName());
}

Try / catch

try {
  trans.prepareExecution(null);
  trans.startThreads();
} catch (KettleTransException e) {
  Throwable root = e;
  while (root.getCause() != null) root = root.getCause();
  log.error("beginProcessing failed; root cause:", root);
}

Prevention

Unwrap the exception cause chain to find the real failure before fixing anything.
Automate connection tests in deployment pipelines for every log table.
Standardize log table DDL across environments with migrations.
Alert on database availability before scheduled transformation windows.

When it happens

Trigger: beginProcessing() catch(KettleException e) block wraps everything: initial log-table writes, date-range calculation, and any inner KettleTransException, rethrowing as KettleTransException(UnableToBeginProcessingTransformation).

Common situations: Any misconfigured transformation/channel/step log table database; unreachable database at transformation start; PDI version upgrade with changed log table schema; environment migration losing connection definitions.

Related errors

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

Appendix: source

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

            @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).
   *
   * @throws KettleException if any errors occur during logging
   */
  protected void writeLogChannelInformation() throws KettleException {
    Database db = null;
    ChannelLogTable channelLogTable = transMeta.getChannelLogTable();

    // PDI-7070: If parent trans or job has the same channel logging info, don't duplicate log entries
    Trans t = getParentTrans();
    if ( t != null ) {
      if ( channelLogTable.equals( t.getTransMeta().getChannelLogTable() ) ) {
        return;

View on GitHub (pinned to f3058517a1)