PostgreSQL

SSL SYSCALL error: EOF detected

SSL SYSCALL error: EOF detected means the connection was closed mid-query. Common causes — timeouts, firewalls, dead connections — and how to fix each.

What it means

SSL SYSCALL error: EOF detected is libpq (the client library behind psql and most Postgres drivers) reporting that the encrypted connection ended abruptly — the operating system returned end-of-file on the socket where libpq expected either more TLS data or a clean shutdown. It’s not a message Postgres’s own error handling produces; it’s the client library’s system call to the OS failing, which is why fixing it is mostly about the network path, not about SQL.

Common causes

  • An idle-connection timeout somewhere between client and server. Firewalls, load balancers, SSH tunnels and cloud NAT gateways commonly kill TCP connections that go quiet for a fixed window. A long transaction, an application that opens a connection and holds it without querying, or a connection pool that keeps stale sessions open, all look “idle” to that middlebox.
  • The server process was killed or crashed — an out-of-memory kill, a manual restart, or the OOM killer targeting a backend running a heavy query.
  • The server ended the session — pg_terminate_backend(), a restart or failover on a managed service, or a session timeout such as idle_in_transaction_session_timeout — and the connection closed before the client read the reason.
  • Packet loss or an unstable link, especially over VPNs, satellite links, or congested Wi-Fi, where the TLS session can’t recover from a dropped packet.
  • A load balancer in front of Postgres (e.g. PgBouncer, HAProxy, a cloud RDS proxy) with its own idle timeout shorter than the client’s.

How to fix it

  1. Enable and tune TCP keepalives so the client sends traffic on an otherwise-idle connection before a middlebox decides to kill it: set keepalives=1, keepalives_idle=<seconds> (and keepalives_interval/keepalives_count) in the connection string, or the equivalent tcp_keepalives_idle server-side setting.
  2. If a firewall or load balancer’s idle timeout is shorter than your longest query, either shorten the query (paginate, batch, add an index) or raise that device’s timeout. Keepalives help only with devices that track TCP activity: a pooler or proxy that times out idle sessions at its own layer ignores them.
  3. Check the Postgres server log around the time of the error for a matching disconnect or an OOM kill; if the server crashed, that’s the real problem to fix, not the network layer.
  4. If it happens consistently through a specific proxy or tunnel, test a direct connection to rule the proxy in or out.
  5. Add basic retry logic in the application for read-only queries, since a transient network blip is not something any client-side setting can fully prevent.

In Tablyne

Tablyne turns on TCP keepalives for Postgres connections by default (the first probe goes out after 10 seconds idle), so a quiet connection doesn’t look dead to a middlebox. The connection form also sets the TLS mode and an optional SSH tunnel per connection, so you can test with and without the tunnel without editing a config file.

See exactly what a query is doing before it runs. Download Tablyne or open the Postgres GUI.

Sources

Frequently asked questions

Is 'SSL SYSCALL error: EOF detected' a bug in my client library? +

Usually not. The message comes from libpq itself when the operating system reports the TCP connection was closed while libpq expected more SSL data. The break almost always happens outside the client: a proxy, load balancer, firewall or NAT device dropping an idle connection, or the server process itself terminating the session.

Why does it only happen on long-running queries? +

Idle-connection timeouts on firewalls, load balancers and some cloud NAT gateways (commonly in the 60–350 second range) close a TCP connection that isn't sending traffic. A long analytical query with no client-side keepalives looks idle to that middlebox even though Postgres is still working.

Does this mean I lost data or corrupted anything? +

No. It means the network connection was severed before the query's result could be delivered (or before a write was acknowledged). If it happened during a write, check whether the transaction actually committed — reconnect and query the data rather than assuming it either succeeded or failed.

Related errors