Connect call failed error doesn't distinguish port mismatch from "server not running"
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 72/100
Research direction
Start in connect_utils.py at the address-iteration loop where the caught OSError is stored as last_error and re-raised. Review the surrounding exception handling, then make connection failures identify the attempted host/port and suggest verifying that PostgreSQL is listening there; check both wrong-port and server-not-running cases and consider the impact of changed exception text.
Written by the indexing model from the issue text.
Description
When connecting to a wrong port (e.g. PostgreSQL configured to listen on 5433 but DATABASE_URL specifies 5432), the error is a raw, unmodified OSError:
ConnectionRefusedError: [Errno 111] Connect call failed ('127.0.0.1', 5432)
This is identical to what you'd see if PostgreSQL wasn't running at all, there's nothing in the message pointing at "wrong port" as a possibility. I found a related case in sqlalchemy/sqlalchemy#8261 where someone spent a while debugging this exact symptom before discovering it was a port mismatch (Debian's non-default port in that case). Issue #694 also hit the identical message back in 2021.
Traced it to connect_utils.py, the OSError is caught as last_error in the address-iteration loop and re-raised verbatim with no added context:
raise last_error or exceptions.TargetServerAttributeNotMatched(...)
Proposed fix: when re-raising, append a short hint with the host/port that was attempted and a suggestion to verify the server is listening there, something like:
raise last_error from None if last_error is None else type(last_error)(
f"{last_error}. Verify PostgreSQL is running and listening on {addr}."
)
(or similar, open to whatever wrapping approach fits the codebase best). One thing worth flagging: modifying the exception text could affect anyone doing exact string matching on the error message, though that seems like an unlikely pattern to rely on. Happy to put together a PR if this direction is welcome.
- Dominant language
- Python
- Stars
- 8.1k
- Forks
- 469
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 9
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from MagicStack/asyncpg
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
MagicStack/asyncpg#1357 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 48/100
MagicStack/asyncpg#1354 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 56/100
MagicStack/asyncpg#1340 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 28/100
MagicStack/asyncpg#1337 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 42/100
MagicStack/asyncpg#1330 · 1 comment ·
All issues in MagicStack/asyncpg
Similar issues
-
Add: hunch Open
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
AbdelStark/awesome-typesafe#104 ·
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
DiamondLightSource/dodal#2211 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
openml/openml-python#1749 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
sipyourdrink-ltd/bernstein#6191 ·