How to Troubleshoot PostgreSQL Database Connectivity Issues

If you get an error when you try to connect to your PostgreSQL database cluster, there are several possible causes and fixes depending on the error. Look up the error you’re receiving below and try the suggested solutions.

Before you begin troubleshooting, check the DigitalOcean status page for ongoing issues in your database’s region.

Connection Refused (Hostname)

psql: could not connect to server: Connection refused         
Is the server running on host "HOSTNAME" (HOSTNAME_DNS) and accepting         
TCP/IP connections on port PORT?

This error means that the server is denying the connection.

Causes

  • Connecting from a computer that is is not allowed in the database’s inbound sources.

  • Using the wrong port in the connection string

Solutions

  • Make sure your computer is allowed in your database’s inbound sources.

  • Check the port in the connection string.

If you still receive this error, you may have a firewall or local DNS issue.

Connection Refused (IP Address)

psql: could not connect to server: Connection refused
Is the server running on host "IP_ADDRESS" and accepting
TCP/IP connections on port PORT?

This error means your computer can’t find a route to the database.

Causes

  • Using the wrong IP address in the connection string

  • Using the database’s private IP address in the connection string and trying to connect from a Droplet that isn’t allowed to access the private network

Solutions

  • Check the IP address in the connection string or use the database’s hostname. We recommend using the hostname over the IP address because the IP address may change, but the hostname will always remain the same.

  • If you’re using the database’s private IP address, make sure you’re connecting from a Droplet that meets the following criteria:

    • The Droplet is on the same DigitalOcean account as the database.
    • The Droplet is in the same datacenter region as the database.
    • The Droplet has private networking enabled and configured.

No Such File or Directory

bash: postgresql://USERNAME:PASSWORD@HOSTNAME:PORT/DBNAME?PARAM: No such file or directory

This error means that the terminal couldn’t execute the command.

Causes

  • Entering the connection string directly into the terminal

Solutions

Authentication Failed

psql: FATAL:  password authentication failed for user "USERNAME"

This error means that the server rejected the credentials in the connection string.

Causes

  • Connecting to the wrong database cluster

  • Using the wrong username or password

Solutions

  • Check the database and username/password combination you’re using. If you’re modifying the connection string, the flags format can make it easier to review changes.

Could Not Translate Hostname to Address

psql: could not translate host name "HOSTNAME" to address: Name or service not known

This error means that psql couldn’t find the host you were trying to connect to.

Causes

  • Using the wrong hostname

  • Problems with DNS resolution

Solutions

  • Rule out mistakes in the connection string by double checking the hostname.

If the hostname isn’t the problem, the computer you’re connecting from may be having problems with DNS resolution.

Database Does Not Exist

psql: FATAL:  database "DBNAME" does not exist

This error means the server couldn’t find the database name you specified.

Causes

  • Connecting to the wrong cluster

  • Connecting to a database that doesn’t exist in the cluster

Solutions

  • Make sure you’re using the right hostname for the cluster.

  • Check that you’ve created the database in the cluster.

Invalid Parameters and Values

psql: invalid URI query parameter: "PARAM"
psql: invalid PARAM value: "VALUE"

These errors mean that one of the arguments to psql was incorrectly formatted.

Causes

  • Typos in the connection string

Solutions

  • Double check the format and values for the connection string. If you’re modifying the connection string, the flags format can make it easier to review changes.