{"record":{"id":"c0e252f80d584fd2","repo":"pentaho/pentaho-kettle","slug":"trans-exception-errorrollingbackuniqueconnection","errorCode":null,"errorMessage":"Trans.Exception.ErrorRollingBackUniqueConnection","messagePattern":"Trans\\.Exception\\.ErrorRollingBackUniqueConnection","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/Trans.java","lineNumber":3021,"sourceCode":"\n    // First we get all the database connections ...\n    //\n    DatabaseConnectionMap map = DatabaseConnectionMap.getInstance();\n    synchronized ( map ) {\n      List<Database> databaseList = new ArrayList<>( map.getMap().values() );\n      for ( Database database : databaseList ) {\n        if ( database.getConnectionGroup().equals( getTransactionId() ) ) {\n          try {\n            // 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 {","sourceCodeStart":3003,"sourceCodeEnd":3039,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/Trans.java#L3003-L3039","documentation":"At the end of a unique-connection transformation, each database's transactions are rolled back when a step reported errors; this error is thrown if the rollback itself fails. Trans wraps the failed database.rollback(true) into a KettleDatabaseException naming the connection.","triggerScenarios":"Running a transformation with 'Unique connections' enabled, at least one step had nrErrors>0, and database.rollback(true) throws (connection already broken/dead-locked/driver error).","commonSituations":"Connection dropped mid-transformation so rollback cannot be sent, DB deadlock or timeout during rollback, driver-level network failure in long-running transformations.","solutions":["Inspect the chained cause for the driver error (connection reset, deadlock, timeout) and address the root DB/network issue","Verify network stability and DB-side timeout settings for long transformations using unique connections","Review step error handling: fix the original step errors that triggered the rollback path","Re-run the transformation; if the connection was already dead the data is effectively rolled back server-side"],"exampleFix":"// before: connection dead, rollback throws\nDB host firewall kills idle connection after 60s\n// after: enable keepalive / adjust unique-connection usage\nDatabase > Options: socketTimeout=0, tcpKeepAlive=true","handlingStrategy":"try-catch","validationCode":"// pre-check connectivity of every unique connection before run\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(\"ErrorRollingBackUniqueConnection\")) {\n    // connection likely dead; verify DB-side state manually, transaction probably already lost\n    reconcileTargets(e.getMessage());\n  } else { throw e; }\n}","preventionTips":["Fix the step errors first — errors trigger the rollback path in the first place","Configure TCP keepalives and adequate timeouts so connections survive long transformations","Check DB-side deadlock detection and lock wait settings","Manually verify target table state after this error: the rollback may or may not have been applied"],"tags":["database","transaction","rollback"],"backgroundTag":"transaction-rollback-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"}