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.
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.