Querious Docs
Account

Common PostgreSQL Connection Errors

Short explanations for the PostgreSQL connection, login, and dump/restore errors you are most likely to run into, and the usual ways to fix them. Each error has its own link target.

Could not connect to server: Connection refused # 

could not connect to server: Connection refused
	Is the server running on host "db.example.com" (203.0.113.4) and accepting
	TCP/IP connections on port 5432?

Nothing accepted a TCP connection at that host and port.

  • Server not running, or on another port — verify and start it.
  • listen_addresses is localhost (the default), so a fresh server refuses all remote TCP. Set listen_addresses = '*' in postgresql.conf and restart.
  • Firewall or cloud security group blocking 5432 — open it, or use an SSH tunnel.
  • Wrong host or port in the connection settings.

Connection to server on socket failed: No such file or directory # 

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?

A local Unix-socket connection was attempted, but there is no socket file at that path.

  • Server not running — start it.
  • Socket is elsewhere — Debian/Ubuntu use /var/run/postgresql; Homebrew and Postgres.app use /tmp. Check SHOW unix_socket_directories; and set the matching path in Querious.
  • You want TCP instead — set the host to 127.0.0.1 and port 5432.

FATAL: password authentication failed for user # 

FATAL:  password authentication failed for user "appuser"

The user name reached the server and matched a rule requiring a password, but the password check failed.

  • Wrong password, wrong user, or an empty password field.
  • The role has no password set — ALTER ROLE appuser PASSWORD 'thepassword';.
  • Encoding mismatch — the stored hash is md5 but the server now wants scram-sha-256 (or the reverse). Set password_encryption to the wanted method, then re-set the password with ALTER ROLE ... PASSWORD ... so a new hash is written.

FATAL: no pg_hba.conf entry for host # 

FATAL:  no pg_hba.conf entry for host "203.0.113.9", user "appuser", database "myapp", no encryption
FATAL:  no pg_hba.conf entry for host "203.0.113.9", user "appuser", database "myapp", SSL on

The server is reachable, but its pg_hba.conf has no line matching this exact combination of client IP + role + database + connection type. The trailing no encryption / SSL on tells you which was tried.

  • IP not covered — add a line and reload with SELECT pg_reload_conf();:
  • # TYPE  DATABASE  USER      ADDRESS          METHOD
host    myapp     appuser   203.0.113.9/32   scram-sha-256
  • Ends with no encryption but the only match is hostssl — turn on SSL in Querious.
  • Ends with SSL on but the only match is hostnossl — turn SSL off, or change the rule to hostssl.
  • Managed providers (RDS, Cloud SQL, Supabase) — add your IP to their network allowlist; you do not edit pg_hba.conf directly.

FATAL: role does not exist # 

FATAL:  role "appuser" does not exist

No login role by that name exists on the server.

  • Typo, or you are pointed at the wrong server.
  • Case — a role created as "AppUser" (quoted) must be given with that exact case; unquoted names fold to lower case.
  • Create it: CREATE ROLE appuser LOGIN PASSWORD 'thepassword';.

FATAL: database does not exist # 

FATAL:  database "myapp" does not exist

The database named for the connection does not exist. When the name matches your user name, it usually means no database was specified and PostgreSQL fell back to "same as the role name".

  • Set the connection's database to one that exists — postgres is the standard administrative database present on nearly every server.
  • Typo, or wrong server.
  • Create it: CREATE DATABASE myapp;.

FATAL: sorry, too many clients already # 

FATAL:  sorry, too many clients already

The server has reached max_connections and cannot open another session.

  • Something is leaking connections. Use the Activity view (or SELECT * FROM pg_stat_activity;) and terminate stragglers with SELECT pg_terminate_backend(pid);.
  • Raise max_connections in postgresql.conf (needs a restart) — but a connection pooler such as PgBouncer is usually the better fix.

Server closed the connection unexpectedly # 

server closed the connection unexpectedly
	This probably means the server terminated abnormally
	before or while processing the request.

An established session was cut off without a clean error from the server.

  • The backend crashed or was killed — the OOM killer, a restart, or another session running pg_terminate_backend. Check the server log.
  • A timeout ended it — statement_timeout, idle_in_transaction_session_timeout, or a proxy idle timeout.
  • A firewall or VPN dropped a long-idle TCP connection — TCP keepalives or an SSH tunnel can help.

FATAL: Peer authentication failed for user # 

FATAL:  Peer authentication failed for user "postgres"

A local Unix-socket connection matched a pg_hba.conf line using the peer method, which requires your operating-system user name to equal the role name. Common right after install, where postgres is only reachable as sudo -u postgres psql.

  • Connect over TCP to 127.0.0.1 with a password instead of the socket.
  • Or change the socket line in pg_hba.conf from peer to scram-sha-256 and reload, and make sure the role has a password.

FATAL: Ident authentication failed for user # 

FATAL:  Ident authentication failed for user "appuser"

A TCP connection matched a pg_hba.conf line using the ident method, which asks an identification service on the client machine for the OS user. That service is usually absent, so it fails.

  • Change that pg_hba.conf line to scram-sha-256 (or md5) and reload — ident is rarely what you want for real clients.

FATAL: remaining connection slots are reserved for superuser # 

FATAL:  remaining connection slots are reserved for non-replication superuser connections

Every ordinary connection slot is in use; only the ones held back by superuser_reserved_connections remain, and your role does not qualify. In practice this is "too many clients" for non-superusers.

  • Free up sessions or raise max_connections — see too many clients already.
  • A superuser can still connect to investigate.

FATAL: the database system is starting up / in recovery mode # 

FATAL:  the database system is starting up
FATAL:  the database system is in recovery mode

The server process is alive but not yet ready — it is replaying the write-ahead log after a crash or unclean shutdown, or a replica has not reached a consistent state.

  • Wait and retry; small databases recover in seconds.
  • If it never finishes, check the server log for recovery progress or errors.

Server does not support SSL / invalid response to SSL negotiation # 

server does not support SSL, but SSL was required
received invalid response to SSL negotiation: ...

The SSL mode you asked for does not match the other end.

  • does not support SSL, but SSL was required — the server is built or configured without TLS (ssl = off). Turn SSL on server-side, or stop requiring it in Querious.
  • invalid response to SSL negotiation — whatever answered is not a PostgreSQL server: wrong host or port, or an HTTP proxy / pooler in between.

SCRAM authentication requires libpq version 10 or above # 

SCRAM authentication requires libpq version 10 or above

The role's password is stored as scram-sha-256 (the modern default), but the client library doing the connecting is older than version 10 and only knows md5.

  • Update to a current Querious build — its bundled client library supports SCRAM.
  • Stopgap: give the role an md5 password — SET password_encryption = 'md5'; then ALTER ROLE appuser PASSWORD 'thepassword'; (with a pg_hba.conf line that allows md5).

Could not translate host name to address # 

could not translate host name "dbhost" to address: nodename nor servname provided, or not known

DNS could not resolve the host name. Nothing was contacted.

  • Typo in the host name.
  • You are not on the VPN that serves that internal name — connect to it, or use the IP.
  • No DNS record — add an /etc/hosts entry or use the IP address.

pg_dump: aborting because of server version mismatch # 

pg_dump: error: aborting because of server version mismatch
pg_dump: detail: server version: 16.2; pg_dump version: 15.6

The pg_dump (or pg_restore) program is older than the server. These tools only work with servers at or below their own version.

  • Point Querious at a newer set of PostgreSQL command-line tools, or install a newer PostgreSQL client package.
  • Dumping an older server with a newer pg_dump is always fine — never the other way around.

pg_restore: input file appears to be a text format dump # 

pg_restore: error: input file appears to be a text format dump. Please use psql.

pg_restore only reads the archive formats (custom -Fc, directory -Fd, tar -Ft). The file you gave it is a plain SQL script (a .sql file).

  • Import it as a SQL file instead of using the archive-restore path.
  • Or regenerate the dump in a restorable format: pg_dump -Fc mydb > mydb.dump.

pg_restore: errors ignored on restore # 

pg_restore: warning: errors ignored on restore: 12

The restore finished, but 12 commands failed and were skipped. On a fresh target this is usually the DROP statements from --clean failing because the objects are not there yet — harmless.

  • Restoring into an empty database? The ... does not exist errors from DROP are expected; ignore them.
  • Real dependency errors (missing roles, extensions, tablespaces) — pre-create them, or restore with --no-owner --no-privileges.
  • Scan the output above the summary for the actual failures.

pg_restore: role does not exist # 

pg_restore: error: could not execute query: ERROR:  role "appuser" does not exist
	Command was: ALTER TABLE public.orders OWNER TO appuser;

The dump records object ownership and privileges by role name, and one of those roles does not exist on the target server.

  • Create the roles first — CREATE ROLE appuser; (attributes do not matter for ownership).
  • Or restore with --no-owner --no-privileges; everything ends up owned by the connecting role.

pg_dump: permission denied for table # 

pg_dump: error: query failed: ERROR:  permission denied for table secrets

The role running the dump cannot read every object it was asked to dump.

  • Dump as a superuser, as the object's owner, or as a role granted pg_read_all_data (PostgreSQL 14+).
  • Or restrict the dump to what you can read (-n schema, -t table).