{"record":{"id":"df41dd62cdc5288e","repo":"pentaho/pentaho-kettle","slug":"trans-exception-errorcommittinguniqueconnection","errorCode":null,"errorMessage":"Trans.Exception.ErrorCommittingUniqueConnection","messagePattern":"Trans\\.Exception\\.ErrorCommittingUniqueConnection","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/Trans.java","lineNumber":3030,"sourceCode":"            // This database connection belongs to this transformation.\n            // Let's roll it back if there is an error...\n            //\n            if ( result.getNrErrors() > 0 ) {\n              try {\n                database.rollback( true );\n                log.logBasic( BaseMessages.getString( PKG, \"Trans.Exception.TransactionsRolledBackOnConnection\",\n                  database.toString() ) );\n              } catch ( Exception e ) {\n                throw new KettleDatabaseException( BaseMessages.getString( PKG,\n                  \"Trans.Exception.ErrorRollingBackUniqueConnection\", database.toString() ), e );\n              }\n            } else {\n              try {\n                database.commit( true );\n                log.logBasic( BaseMessages.getString( PKG, \"Trans.Exception.TransactionsCommittedOnConnection\", database\n                  .toString() ) );\n              } catch ( Exception e ) {\n                throw new KettleDatabaseException( BaseMessages.getString( PKG,\n                  \"Trans.Exception.ErrorCommittingUniqueConnection\", database.toString() ), e );\n              }\n            }\n          } catch ( Exception e ) {\n            log.logError( BaseMessages.getString( PKG, \"Trans.Exception.ErrorHandlingTransformationTransaction\",\n              database.toString() ), e );\n            result.setNrErrors( result.getNrErrors() + 1 );\n          } finally {\n            try {\n              // This database connection belongs to this transformation.\n              database.closeConnectionOnly();\n            } catch ( Exception e ) {\n              log.logError( BaseMessages.getString( PKG, \"Trans.Exception.ErrorHandlingTransformationTransaction\",\n                database.toString() ), e );\n              result.setNrErrors( result.getNrErrors() + 1 );\n            } finally {\n              // Remove the database from the list...\n              //","sourceCodeStart":3012,"sourceCodeEnd":3048,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/Trans.java#L3012-L3048","documentation":"At transformation end with unique connections, each database's transaction is committed when no step errors occurred; this is thrown when database.commit(true) fails. The failing connection name is embedded in the message and the driver error is chained as cause.","triggerScenarios":"Transformation configured with unique connections completes without step errors, but database.commit(true) throws (connection lost, constraint violation deferred to commit, DB crash).","commonSituations":"Network drop between step execution and commit, deferred constraint/unique-index violations surfacing only at COMMIT, DB-side resource limits hitting during commit of a huge transaction.","solutions":["Read the chained cause: if it's a constraint violation, fix the data; if connection loss, fix network/timeout settings","Check for deferred constraints or triggers on the target tables that fail at commit time","Break very large transactions into smaller batches to avoid DB resource limits at commit","Verify the DB did not kill the session (look at server logs for OOM kill, idle timeouts)"],"exampleFix":"// before: deferred FK fails at commit\nINSERT child rows with missing parent in same unique connection\n// after: insert parents first or add FK constraint as DEFERRABLE INITIALLY DEFERRED with valid data","handlingStrategy":"try-catch","validationCode":"// validate data / constraints before large unique-connection transactions\nfor (DatabaseMeta dbMeta : transMeta.getUsedDatabaseConnections()) {\n  if (!dbMeta.testConnectionSuccess()) throw new IllegalStateException(\"DB unreachable: \" + dbMeta.getName());\n}","typeGuard":null,"tryCatchPattern":"try {\n  trans.waitUntilFinished();\n} catch (KettleDatabaseException e) {\n  if (e.getMessage().contains(\"ErrorCommittingUniqueConnection\")) {\n    Throwable cause = e.getCause();\n    if (cause instanceof SQLException && ((SQLException) cause).getErrorCode() == <constraint-violation-code>) {\n      fixDataAndRetry();\n    }\n  } else { throw e; }\n}","preventionTips":["Inspect chained cause for constraint violations — clean data before running","Avoid one giant transaction across unique connections; batch the work","Check DB server logs after the error (commit-time OOM, session kill, deferred constraint reports)","Test target tables' constraints/triggers under load before production runs"],"tags":["database","transaction","commit"],"backgroundTag":"transaction-commit-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"}