{"record":{"id":"ca13165f13a20478","repo":"hibernate/hibernate-orm","slug":"exception-pulsing-transactioncoordinator","errorCode":null,"errorMessage":"Exception pulsing TransactionCoordinator","messagePattern":"Exception pulsing TransactionCoordinator","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/AbstractSharedSessionContract.java","lineNumber":1403,"sourceCode":"\t\t}\n\t\treturn transaction;\n\t}\n\n\tprotected void checkTransactionSyncStatus() {\n\t\tpulseTransactionCoordinator();\n\t\tdelayedAfterCompletion();\n\t}\n\n\tprotected void pulseTransactionCoordinator() {\n\t\tif ( !isClosed() ) {\n\t\t\ttry {\n\t\t\t\ttransactionCoordinator.pulse();\n\t\t\t}\n\t\t\tcatch (HibernateException e) {\n\t\t\t\tthrow e;\n\t\t\t}\n\t\t\tcatch (RuntimeException e) {\n\t\t\t\tthrow new HibernateException( \"Exception pulsing TransactionCoordinator\", e );\n\t\t\t}\n\t\t}\n\t}\n\n\t@Override\n\tpublic void joinTransaction() {\n\t\tcheckOpen();\n\t\ttry {\n\t\t\t// For a non-JTA TransactionCoordinator, this just logs a WARNing\n\t\t\ttransactionCoordinator.explicitJoin();\n\t\t}\n\t\tcatch ( TransactionRequiredForJoinException e ) {\n\t\t\tthrow new TransactionRequiredException( e.getMessage() );\n\t\t}\n\t\tcatch ( HibernateException he ) {\n\t\t\tthrow getExceptionConverter().convert( he );\n\t\t}\n\t}","sourceCodeStart":1385,"sourceCodeEnd":1421,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/AbstractSharedSessionContract.java#L1385-L1421","documentation":"Before executing JDBC work, SharedSessionContract pulses the TransactionCoordinator to resume/join the transaction for the current thread. Any non-Hibernate RuntimeException from that pulse (driver, connection pool, JTA resume failure) is wrapped in HibernateException('Exception pulsing TransactionCoordinator') with the real cause attached. It marks infrastructure failure during transaction re-association, not an API misuse.","triggerScenarios":"The underlying connection was killed or invalidated by the pool (eager eviction, database wait_timeout) before the pulse; XA transaction resume/re-register fails (Narayana recovery issues, tx timeouts); driver throws while beforeQuery/afterTransaction hooks re-attach resources.","commonSituations":"MySQL wait_timeout closing pooled connections and the next query pulsing a dead coordinator; HikariCP/Agroal eviction racing an in-flight session; WildFly/Narayana XA recovery problems after a crash; app/container resumed from suspend with stale connections.","solutions":["Inspect HibernateException.getCause() — the SQLException/XAException/Narayana exception identifies the real failure and dictates the fix.","Stale connections: set pool maxLifetime below the database idle timeout and enable checkout validation (connection test query or isValid).","JTA resume failures: check XA recovery logs and transaction timeouts; start a fresh transaction rather than reusing the session.","Retry the unit of work in a new session/transaction once the resource is healthy; do not retry on the same broken session."],"exampleFix":"// before: pooled connection invalidated by db idle timeout, next query throws\nsession.createQuery(...).list();\n// after: bounded maxLifetime + validation, and failover to a fresh session\n// hikari: maximumPoolLifetime < db wait_timeout, connectionTestQuery or isValid on checkout","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    return session.createQuery(...).list();\n} catch (HibernateException e) {\n    if (\"Exception pulsing TransactionCoordinator\".equals(e.getMessage())) {\n        Throwable root = rootCause(e); // inspect SQLException / XAException\n        if (isTransientConnectionFailure(root)) {\n            try (Session fresh = sessionFactory.openSession()) {\n                fresh.beginTransaction();\n                return fresh.createQuery(...).list(); // one retry on a healthy session\n            }\n        }\n    }\n    throw e;\n}","preventionTips":["Keep pool maxLifetime below the database connection idle timeout","Enable connection validation on checkout so dead connections never reach the coordinator","Always unwrap and log the cause; the wrapper message alone hides the real failure"],"tags":["hibernate","transactions","jdbc","connection-pool","jta"],"backgroundTag":"transaction-coordinator-failure","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}