- SQLSTATE
- 08001
- Condition name
sqlclient_unable_to_establish_sqlconnection- Product
- PostgreSQL
- Versions
- libpq and psql 14 to 18 (older clients use the wording shown in the variants)
- Last reviewed
- 24 October 2026
On this page
What it means
SQLSTATE 08001 is the standard code for a client that could not establish a connection at all: nothing accepted the connection at that address and port, or the network did not let it through.
Before any login can happen, the client has to reach a server process listening on the given host and port (5432 by default) or Unix-domain socket. When nothing is listening there, the operating system answers Connection refused (TCP) or No such file or directory (socket), and libpq reports it in the form above. As the documentation stresses, Connection refused here does not mean the server got your request and rejected it; a server that rejects you produces a FATAL message instead, such as 28000 or 28P01. Other kernel messages such as Connection timed out usually mean a network problem or a firewall dropping the traffic.
Because the server was never reached, it sends no SQLSTATE: libpq and psql print only the message. Drivers attach the standard connection-exception code themselves, and 08001 (sqlclient_unable_to_establish_sqlconnection) is the one for "unable to establish a connection"; some drivers report these failures with that code. A PostgreSQL server also raises 08001 itself when it fails to connect onwards to another server, for example through postgres_fdw or dblink.
The message always shows the address or socket path the client tried, which is the first thing to check. A very common cause is a server that listens only on localhost: listen_addresses defaults to localhost, so remote TCP connections are refused until it is changed.
Common causes
- The PostgreSQL server is not running (stopped, crashed, still starting, or failed to start after a configuration change).
- The server listens only on localhost (the default listen_addresses), so connections from other machines or containers are refused.
- The client uses the wrong host or port: a second server on 5433, a container port that is not published, or localhost inside a container, which is the container itself.
- A firewall, security group or cloud network rule blocks port 5432 (this usually gives Connection timed out rather than refused).
- For socket connections, the client looks in a different socket directory than the server uses (for example /tmp versus /var/run/postgresql).
- The host name does not resolve, or resolves to the wrong address.
Diagnose it
Read-only These queries only read the system catalogs (pg_catalog, information_schema) and statistics views such as pg_stat_activity and pg_locks. They do not change data, roles or settings, so they are safe to run first.
Read the address in the message, then test it from the client
The message names the host, address and port (or socket path) the client tried. From the client machine, run pg_isready -h server.joe.com -p 5432: it reports whether a server is accepting connections there, without logging in. A TCP test such as nc -vz server.joe.com 5432 or PowerShell's Test-NetConnection server.joe.com -Port 5432 separates a closed port from a blocked network.
On the server: is PostgreSQL running and where is it listening?
On the server machine, check the service (for example systemctl status postgresql or the Windows Services console) and the server log for start-up errors. Then connect locally and check the listening settings.
SELECT name, setting
FROM pg_settings
WHERE name IN ('listen_addresses', 'port', 'unix_socket_directories');listen_addresses = localhost means only local TCP connections are accepted. The port must match the client's, and unix_socket_directories must contain the directory the client looks in for socket connections.
Which address and port answered this session?
SELECT inet_server_addr() AS server_address,
inet_server_port() AS server_port;From a working connection, the address and port the server accepted it on; both are NULL for a Unix-domain socket connection.
How to fix it
Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.
Start the server, or fix what stops it starting
Changes database stateStart the service (for example sudo systemctl start postgresql, pg_ctl start -D datadir or the Windows service). If it does not stay up, the server log says why: a port already in use, a bad setting in postgresql.conf, or a permissions problem on the data directory.
Listen on the right network interface
Changes configurationTo accept remote connections, set listen_addresses to the server's own address (or the specific interfaces clients use), then restart the server; this setting is read only at start. Pair it with narrow pg_hba.conf lines and a firewall rule for the client addresses only. Do not combine listening on every interface with broad pg_hba.conf rules that let any address in.
Caution: Needs a restart, which disconnects every session. Opening the port to a network also needs firewall rules and pg_hba.conf lines limited to the clients that should connect.
ALTER SYSTEM SET listen_addresses = 'localhost,10.0.0.5';
-- then restart the serverUse the right host, port and socket in the client
Client or network sidePass host and port explicitly (psql -h server.joe.com -p 5432, or host=... port=... in the connection string). Inside a container, localhost is the container itself: use the database container's service name. For socket connections, set host=/var/run/postgresql (a directory) to match the server's unix_socket_directories.
Open the network path
Client or network sideIf the test times out rather than being refused, allow TCP port 5432 from the client's address in the host firewall and any cloud security group or network ACL, and check that the host name resolves to the right address. Add connect_timeout to the connection string so clients fail quickly instead of waiting for the operating system default.
Examples
No server listening on the host and port
Shown as documented in the PostgreSQL documentation (Server Setup and Operation, Starting the Database Server, Client Connection Problems). This example needs a client and a network address with no PostgreSQL server listening, which PGlite does not provide, so it was not reproduced here.
-- From a shell on the client:
-- psql -h server.joe.com -p 5432 -U andym testdbpsql: error: connection to server at "server.joe.com" (123.123.123.123), port 5432 failed: Connection refused
Is the server running on that host and accepting TCP/IP connections?
No server socket in the directory the client looks in
Shown as documented in the PostgreSQL documentation (Starting the Database Server, Client Connection Problems). The socket directory depends on how the client was built; many Linux packages use /var/run/postgresql. This example needs a client and a local socket path with no server, which PGlite does not provide, so it was not reproduced here.
-- From a shell on the server machine, with no host given:
-- psql testdbpsql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
Is the server running locally and accepting connections on that socket?
How to prevent it
Monitor the server with pg_isready or your platform's health checks, and make the service start automatically. Keep host, port and database in one configuration source per environment, and in container setups wait for the database to accept connections before starting the application.
Decide deliberately which interfaces the server listens on, and document the firewall and pg_hba.conf rules that go with it, so remote access is opened only for the clients that need it.
Common questions
How do I fix "Connection refused" when connecting to PostgreSQL?
Check that the server is running, that it listens on the address you use (listen_addresses defaults to localhost) and on the same port, and that the client uses the right host and port. pg_isready -h host -p port from the client shows quickly whether anything accepts connections there.
Is "Connection refused" a password or pg_hba.conf problem?
No. The connection never reached a PostgreSQL server that could check anything. Password and pg_hba.conf problems produce FATAL messages from the server, such as 28P01 or 28000, after the connection is made.
What is the difference between "Connection refused" and "Connection timed out"?
Refused means the machine answered but nothing listens on that port. Timed out means no answer came back, usually because a firewall drops the traffic or the address is unreachable.
Why does the error mention /tmp/.s.PGSQL.5432?
No host was given, so the client tried a Unix-domain socket in its default directory. Either the server is not running, or it puts its socket in another directory; pass -h with that directory, or -h localhost to use TCP.
Learn more on CodeWithSQL
Official documentation
- Starting the database server: client connection problems
- libpq connection parameters
- Connections and authentication settings (listen_addresses, port)
- pg_isready
Last technically reviewed 24 October 2026; examples and diagnostics run on PostgreSQL 18.6 documentation; SQL-level parts in PGlite 0.5.11. SQL-level examples were run in PGlite (PostgreSQL compiled to WebAssembly); examples that need a running server are shown as documented in the PostgreSQL documentation.