{"record":{"id":"9a8338c65d66dda3","repo":"pentaho/pentaho-kettle","slug":"trans-exception-unabletobeginprocessingtransformation","errorCode":null,"errorMessage":"Trans.Exception.UnableToBeginProcessingTransformation","messagePattern":"Trans\\.Exception\\.UnableToBeginProcessingTransformation","errorType":"exception","errorClass":"KettleTransException","httpStatus":null,"severity":"critical","filePath":"engine/src/main/java/org/pentaho/di/trans/Trans.java","lineNumber":2610,"sourceCode":"            @Override\n            public void transFinished( Trans trans ) {\n              timer.cancel();\n            }\n          } );\n        }\n      } catch ( KettleException e ) {\n        throw new KettleTransException( BaseMessages.getString( PKG, \"Trans.Exception.ErrorWritingLogRecordToTable\",\n          logTable ), e );\n      } finally {\n        // If we use interval logging, we keep the connection open for performance reasons...\n        //\n        if ( transLogTableDatabaseConnection != null && ( intervalInSeconds <= 0 ) ) {\n          transLogTableDatabaseConnection.disconnect();\n          transLogTableDatabaseConnection = null;\n        }\n      }\n    } catch ( KettleException e ) {\n      throw new KettleTransException( BaseMessages.getString( PKG,\n        \"Trans.Exception.UnableToBeginProcessingTransformation\" ), e );\n    }\n  }\n\n  /**\n   * Writes log channel information to a channel logging table (if one has been configured).\n   *\n   * @throws KettleException if any errors occur during logging\n   */\n  protected void writeLogChannelInformation() throws KettleException {\n    Database db = null;\n    ChannelLogTable channelLogTable = transMeta.getChannelLogTable();\n\n    // PDI-7070: If parent trans or job has the same channel logging info, don't duplicate log entries\n    Trans t = getParentTrans();\n    if ( t != null ) {\n      if ( channelLogTable.equals( t.getTransMeta().getChannelLogTable() ) ) {\n        return;","sourceCodeStart":2592,"sourceCodeEnd":2628,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/Trans.java#L2592-L2628","documentation":"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.","triggerScenarios":"beginProcessing() catch(KettleException e) block wraps everything: initial log-table writes, date-range calculation, and any inner KettleTransException, rethrowing as KettleTransException(UnableToBeginProcessingTransformation).","commonSituations":"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.","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."],"exampleFix":"// before: transformation starts without any log database reachable\nKettleTransException: UnableToBeginProcessingTransformation\n// after: start DB, test connection in Log tab, then relaunch transformation","handlingStrategy":"try-catch","validationCode":"// Pre-flight all log table connections configured on the transformation\nfor (LogTableInterface lt : List.of(transMeta.getTransLogTable(), transMeta.getChannelLogTable(), transMeta.getStepLogTable(), transMeta.getMetricsLogTable())) {\n  DatabaseMeta dm = lt.getDatabaseMeta();\n  if (dm != null && (dm.getID() == null)) throw new IllegalStateException(\"Unresolved log connection: \" + dm.getName());\n}","typeGuard":null,"tryCatchPattern":"try {\n  trans.prepareExecution(null);\n  trans.startThreads();\n} catch (KettleTransException e) {\n  Throwable root = e;\n  while (root.getCause() != null) root = root.getCause();\n  log.error(\"beginProcessing failed; root cause:\", root);\n}","preventionTips":["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."],"tags":["database","logging","startup","transformation"],"backgroundTag":"database-write-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"}