How to fix 25002: branch_transaction_already_active in PostgreSQL

Query the database to see all currently active transactions:

SELECT pid, usename, application_name, state, query_start, query
FROM pg_stat_activity
WHERE state = 'active'
  AND pid = pg_backend_pid();

This shows if your current connection has an active transaction that wasn't properly closed.

For all active transactions across the database:

SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE state = 'active'
ORDER BY duration DESC;

If you have control over the session, explicitly end the current transaction:

-- If you want to commit the pending changes
COMMIT;

-- Or if you want to discard the changes
ROLLBACK;

After this, you should be able to start a new transaction on the same branch.

Check your application code for proper transaction handling. Every transaction start must have a corresponding commit or rollback:

Java/JTA example:

UserTransaction ut = ...;
try {
    ut.begin();
    // Your database operations
    ut.commit();
} catch (Exception e) {
    ut.rollback(); // CRITICAL: Always rollback on error
    throw e;
} finally {
    // Ensure transaction is closed
}

Common mistakes:
- Missing rollback in exception handlers
- Early returns that skip transaction cleanup
- Nested transaction attempts on the same connection

XA transactions require the max_prepared_transactions parameter to be set. Edit postgresql.conf:

max_prepared_transactions = 100  # Should be >= max_connections

Restart PostgreSQL for changes to take effect:

sudo systemctl restart postgresql

Verify the setting:

SHOW max_prepared_transactions;

If this is set to 0, XA transactions cannot work properly.

If using connection pooling (HikariCP, c3p0, DBCP), ensure connections are properly cleaned between uses:

HikariCP example (Java):

HikariConfig config = new HikariConfig();
config.setAutoCommit(true);  // Auto-commit when connection is returned
config.setConnectionTestQuery("SELECT 1");

Configure connection validation:
- Test connections before use
- Set reasonable connection timeouts
- Enable auto-commit for non-XA connections

If a transaction is stuck and cannot be closed normally, you can terminate the backend process:

-- Find the process ID (pid) from pg_stat_activity
SELECT pg_terminate_backend(12345);  -- Replace with actual pid

Warning: This forcibly kills the connection and rolls back the transaction. Only use this for stuck sessions that cannot be recovered normally.