psycopg2.InterfaceError: connection already closed

What this error actually means

A `psycopg2` connection is a Python object wrapping a TCP socket. This error means the object still exists and your code still holds a reference to it, but the underlying socket is no longer usable — either because something closed it, or because the driver marked it dead after a previous failure. The driver refuses the operation locally without going near the network, which is why the traceback is short and contains no PostgreSQL error code at all.

The mechanism that trips most teams: `psycopg2` closes the connection *itself* when a network-level error occurs. If a query dies with `server closed the connection unexpectedly`, the connection is marked closed from that moment on. Every later use of the same object raises `InterfaceError` instead of the original cause. So the exception you are looking at is frequently the second, third and hundredth symptom of one earlier event whose real message was logged elsewhere — or swallowed.

That distinction decides the fix. `OperationalError: server closed the connection unexpectedly` names why the socket died. `InterfaceError: connection already closed` only tells you that something already did. Chasing the second one without finding the first one is the usual reason this bug survives three attempted fixes.

How to diagnose it

grep -n -m5 -E 'OperationalError|server closed the connection|SSL (SYSCALL|connection has been closed)' app.log

grep -E 'terminating connection|disconnection: session time' /var/log/postgresql/postgresql-*.log | tail -20

python -c "import psycopg2; c=psycopg2.connect(dsn); c.close(); print(c.closed)"

logger.info('pid=%s conn=%s', os.getpid(), id(conn))

The fix

Make dead connections detectable before use rather than during use. With SQLAlchemy that is `create_engine(dsn, pool_pre_ping=True, pool_recycle=<seconds>)`: pre-ping issues a trivial round trip on checkout and transparently replaces a connection that fails it, and `pool_recycle` discards connections older than a bound. Set the recycle value *below* the shortest idle timeout in the path — PgBouncer’s `server_idle_timeout`, the load balancer’s idle timeout, whichever is smaller. If you manage raw `psycopg2` connections yourself, the equivalent is checking `conn.closed` and reconnecting on checkout.

Stop reusing a connection after any exception that could be network-level. On error, discard the connection instead of returning it to the pool. With a pool this is an invalidation, not a close; with raw connections it is `conn.close()` and open a new one. A connection that has seen a socket error is never safe to reuse, regardless of what the retry logic believes.

For the fork case, never inherit a connection. Open connections lazily after the worker starts, or dispose the pool in the post-fork hook — SQLAlchemy’s `engine.dispose()` in Gunicorn’s `post_fork` and Celery’s `worker_process_init` signal. If you preload the application, the pool must be created per worker.

Make retries idempotent and bounded before you add them. Retrying a read after a stale-connection failure is safe; retrying a write whose transaction outcome you do not know is how duplicate rows get created. Retry at the transaction boundary with a fresh connection, not by re-issuing a statement on the dead one.

Set TCP keepalives on the connection so a silently dropped socket is detected in seconds rather than at next use: `keepalives=1 keepalives_idle=30 keepalives_interval=10 keepalives_count=5` in the DSN. This converts a mysterious hang into a prompt, catchable error.

# Dead connection handed out, and reused after failing
conn = pool.getconn()
try:
    with conn.cursor() as cur:
        cur.execute(sql)
finally:
    pool.putconn(conn)          # returns a possibly-dead connection to the pool

# Validate on checkout, discard on any network-level failure
engine = create_engine(
    dsn,
    pool_pre_ping=True,         # cheap round trip before handing the connection over
    pool_recycle=240,           # below PgBouncer server_idle_timeout / LB idle timeout
    connect_args={
        "keepalives": 1,
        "keepalives_idle": 30,
        "keepalives_interval": 10,
        "keepalives_count": 5,
    },
)

# Per-worker pool, never inherited across fork()
def post_fork(server, worker):
    engine.dispose(close=False)

How to stop it coming back

• Keep `pool_recycle` strictly below every idle timeout in the path, and record those timeouts next to the setting so a proxy change does not silently break it
• Log the first exception on a connection at error level and invalidate the connection there; a broad `except Exception: pass` around database work turns one diagnosable failure into a thousand undiagnosable ones
• Dispose pools in `post_fork` / `worker_process_init` as a matter of course, even when you do not preload today
• Treat a failover drill as a test: kill the primary in staging and assert the service recovers without operator action
• Alarm on the rate of connection establishment, not just on errors — a pool that silently recreates connections constantly is telling you something is closing them

FAQ

Related

Other errors engineers hit next to this one

• CrashLoopBackOff
• ImagePullBackOff / ErrImagePull
• Readiness probe failed
• Liveness probe failed during startup
• CreateContainerConfigError — missing Secret or ConfigMap
• Evicted — node disk pressure
• runAsNonRoot and image will run as root
• JVM container killed despite available Java heap