Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

PostgreSQL JDBC: an I/O error occurred while sending to the backend

Errororg.postgresql.util.PSQLException: An I/O error occurred while sending to the backend.

Short answer

This error means the connection the driver was about to use was already closed. Something ended it while it sat idle in the pool or while a read ran too long. Check three things: a firewall or load balancer dropping idle sockets, a server-side idle timeout, and a JDBC socketTimeout set lower than your slowest query.

  • Applies to PostgreSQL 16, PostgreSQL 17, pgJDBC 42.7, HikariCP 6, Java 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at when it happens. If the first query after a quiet period fails and the retry works, a connection died while idle. If a long query fails every time, a read timeout is the likely cause.

    grep -n "I/O error" app.log | head -n 5
    psql -c "SHOW idle_session_timeout;" -c "SHOW idle_in_transaction_session_timeout;"
  2. 2Match what you see, then jump to its fix

    1. 1The first query after a pause fails; the retry worksA network device or the server dropped an idle pooled connectionFix
    2. 2The SHOW commands above return a non-zero value, and failures line up with that timeThe PostgreSQL server ends idle sessionsFix
    3. 3A long query always fails at the same number of secondssocketTimeout is shorter than your slowest queryFix

What does the error look like?

  • org.postgresql.util.PSQLException: An I/O error occurred while sending to the backend.

Cause 1 of 3

A network device or the server dropped an idle pooled connection

1Check

The pool hands out a connection that was closed while idle. HikariCP documents maxLifetime (default 30 minutes) and keepaliveTime (default 2 minutes) for this, and recommends maxLifetime a few seconds below any database or infrastructure time limit.

grep -rn 'maxLifetime\|keepaliveTime\|tcpKeepAlive' src/main/resources/

2Fix

Keep the pool's maximum lifetime below the shortest limit on the path (firewall, NAT, load balancer, proxy) and turn on the driver's TCP keep-alive.

# application.properties
spring.datasource.url=jdbc:postgresql://db.example.com:5432/appdb?tcpKeepAlive=true
spring.datasource.hikari.max-lifetime=600000
spring.datasource.hikari.keepalive-time=120000

3Verify

Leave the app idle past the old failure time, then run a query.

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/health

Confirmed by github.com

Did this fix it?

Cause 2 of 3

The PostgreSQL server ends idle sessions

1Check

idle_session_timeout terminates a session that waits for a query, and idle_in_transaction_session_timeout terminates one that sits idle inside an open transaction. Both default to 0 (off). The manual warns that poolers may not cope with unexpected closures.

SHOW idle_session_timeout;
SHOW idle_in_transaction_session_timeout;

2Fix

For pooled application users, leave idle_session_timeout at 0 or make the pool's maxLifetime and idleTimeout shorter than it. For idle-in-transaction kills, find the code that opens a transaction and then waits, and close it sooner.

ALTER ROLE app_user RESET idle_session_timeout;

3Verify

Reconnect and check the value is the one you meant.

psql -U app_user -d appdb -c 'SHOW idle_session_timeout;'

Confirmed by postgresql.org

Did this fix it?

Cause 3 of 3

socketTimeout is shorter than your slowest query

1Check

The driver's socketTimeout limits how long a read from the server may take, and the connection is closed when it expires. Its default is 0 (no limit), so this only applies if someone set it.

grep -rn 'socketTimeout' src/main/resources/ config/

2Fix

Raise socketTimeout above the longest query you allow, or remove it and enforce limits with statement_timeout on the server.

jdbc:postgresql://db.example.com:5432/appdb?socketTimeout=300

3Verify

Run the slow query that failed.

psql -d appdb -c 'SELECT pg_sleep(60);'

Confirmed by jdbc.postgresql.org

Did this fix it?

How do I stop it coming back?

  • Set the pool's maxLifetime a few seconds below the shortest connection limit on the network path.
  • Enable tcpKeepAlive in the JDBC URL.
  • Set timeouts deliberately: statement_timeout on the server, socketTimeout only as a last resort.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Databases

Java cannot load org.postgresql.Driver

Class not found loading JDBC org.postgresql.Driver

The PostgreSQL JDBC jar is not on the classpath of the process that runs your code.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.