PostgreSQL JDBC: an I/O error occurred while sending to the backend
org.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.
Fix it fast
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;"2Match what you see, then jump to its fix
- 1
The first query after a pause fails; the retry worksA network device or the server dropped an idle pooled connectionFix - 2
The SHOW commands above return a non-zero value, and failures line up with that timeThe PostgreSQL server ends idle sessionsFix - 3
A long query always fails at the same number of secondssocketTimeout is shorter than your slowest queryFix
- 1
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=1200003Verify
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/healthConfirmed by github.com
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
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=3003Verify
Run the slow query that failed.
psql -d appdb -c 'SELECT pg_sleep(60);'Confirmed by jdbc.postgresql.org
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
Spring Boot fails on startup: HikariPool-1 exception during pool initialization
Caused by: ... (the underlying driver exception)
HikariCP opens one connection when the pool starts, and the startup fails when that connection fails.
3 causes, each with a fixDatabases
H2 in PostgreSQL mode still behaves differently from PostgreSQL
Names or null ordering differ from PostgreSQL in test results
H2 compatibility modes are switched on in the JDBC URL and cover only a small part of the differences between databases.
4 causes, each with a fixDatabases
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 fixDatabases
TypedQuery rejects a query that selects several columns
The select list of the query must contain only a single item
The Jakarta Persistence rule is that the select list of a typed query holds a single item.
4 causes, each with a fixDatabases
executeQuery on an INSERT or UPDATE throws in PostgreSQL JDBC
No results returned by the query
executeQuery is for statements that return rows.
2 causes, each with a fixDatabases
Saving a UUID through JDBC fails with a type mismatch
Hint: You will need to rewrite or cast the expression.
pgJDBC sends setString parameters as varchar, and PostgreSQL will not store varchar in a uuid column without a conversion.
3 causes, each with a fix