The Fix
Refactored the connection generator to handle connection timeouts more appropriately.
Based on closed psycopg/psycopg issue #1089 · PR/commit linked
Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.
@@ -419,9 +419,11 @@ def prepared_max(self, value: int) -> None:
@classmethod
- def _connect_gen(cls, conninfo: str = "") -> PQGenConn[Self]:
+ def _connect_gen(
+ cls, conninfo: str = "", *, timeout: float = 0.0
repro.py
@pytest.fixture(autouse=True)
def init(self, generic_client):
self.org_created_at = datetime.now(tz=UTC)
with time_machine.travel(self.org_created_at, tick=False):
with self.db.session_scope() as session:
self.user = create_test_user(session)
verify
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
fix.md
Option A — Apply the official fix\nRefactored the connection generator to handle connection timeouts more appropriately.\nWhen NOT to use: Do not use this fix if the timeout behavior is expected to be overridden by external factors.\n\n
Why This Fix Works in Production
- Trigger: 3.2.x series raises "connection timeout expired" without actually waiting for connection timeout
- Mechanism: Connection timeout handling was not correctly implemented in the connection generator
Production impact:
- If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.
Why This Breaks in Prod
- Shows up under Python 3.12 in real deployments (not just unit tests).
- Connection timeout handling was not correctly implemented in the connection generator
- Production symptom (often without a traceback): 3.2.x series raises "connection timeout expired" without actually waiting for connection timeout
Proof / Evidence
- GitHub issue: #1089
- Fix PR: https://github.com/psycopg/psycopg/pull/766
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.80
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.69
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Okay thanks for keeping it unlocked, despite closing. I cannot reproduce it when running with PSYCOPG_IMPL=python, though. If it's time (maybe time-machine) related, it seems…”
“The difficulty in this is that it apparently _randomly_ fails. Also, 3.1.x works always, 3.2.x is where things fail randomly.”
“Yeah, seems to be some interop problem with time-machine and C build of 3.2.x here”
“I do believe that you are doing something that affects the timer”
Failure Signature (Search String)
- 3.2.x series raises "connection timeout expired" without actually waiting for connection timeout
- A bit randomly, after some (tens of) tests, connections start to fail, again randomly.
Copy-friendly signature
signature.txt
Failure Signature
-----------------
3.2.x series raises "connection timeout expired" without actually waiting for connection timeout
A bit randomly, after some (tens of) tests, connections start to fail, again randomly.
Error Message
Signature-only (no traceback captured)
error.txt
Error Message
-------------
3.2.x series raises "connection timeout expired" without actually waiting for connection timeout
A bit randomly, after some (tens of) tests, connections start to fail, again randomly.
Minimal Reproduction
repro.py
@pytest.fixture(autouse=True)
def init(self, generic_client):
self.org_created_at = datetime.now(tz=UTC)
with time_machine.travel(self.org_created_at, tick=False):
with self.db.session_scope() as session:
self.user = create_test_user(session)
Environment
- Python: 3.12
What Broke
Connections fail immediately instead of waiting for the specified timeout, causing unexpected failures.
Why It Broke
Connection timeout handling was not correctly implemented in the connection generator
Fix Options (Details)
Option A — Apply the official fix
Refactored the connection generator to handle connection timeouts more appropriately.
When NOT to use: Do not use this fix if the timeout behavior is expected to be overridden by external factors.
Option D — Guard side-effects with OnceOnly Guardrail for side-effects
Mitigate duplicate external side-effects under retries/timeouts/agent loops by gating the operation before calling external systems.
- Place OnceOnly between your code/agent and real side-effects (Stripe, emails, CRM, APIs).
- Use a stable key per side-effect (e.g., customer_id + action + idempotency_key).
- Fail-safe: configure fail-open vs fail-closed based on blast radius and spend risk.
Show example snippet (optional)
onceonly.py
from onceonly import OnceOnly
import os
once = OnceOnly(api_key=os.environ["ONCEONLY_API_KEY"], fail_open=True)
# Stable idempotency key per real side-effect.
# Use a request id / job id / webhook delivery id / Stripe event id, etc.
event_id = "evt_..." # replace
key = f"stripe:webhook:{event_id}"
res = once.check_lock(key=key, ttl=3600)
if res.duplicate:
return {"status": "already_processed"}
# Safe to execute the side-effect exactly once.
handle_event(event_id)
When NOT to use: Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.
Fix reference: https://github.com/psycopg/psycopg/pull/766
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Do not use this fix if the timeout behavior is expected to be overridden by external factors.
- Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.
Verify Fix
verify
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Did This Fix Work in Your Case?
Quick signal helps us prioritize which fixes to verify and improve.
Prevention
- Add a stress test that runs high-concurrency workloads and fails on thread dumps / blocked locks.
- Enable watchdog dumps in prod (faulthandler, thread dump endpoint) to capture deadlocks quickly.
- Make timeouts explicit and test them (unit + integration) to avoid silent behavior changes.
- Instrument retries (attempt count + reason) and alert on spikes to catch dependency slowdowns.
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.