Troubleshoot resource connections

Learn about common data source connection issues and how to resolve them.

Retool can connect to many databases and APIs. Certain data sources may have specific setup requirements, such as allowed IPs or required keys. Where necessary, we document these requirements. Refer to the integration's documentation when configuring your resource and use the following information as you troubleshoot any connection issues. If you need to make changes with your data source, refer to their documentation for more information and guidance.

Some resources include testing options that you can use to troubleshoot connection issues. These options are displayed when you create or edit a resource, and include a debugging console that displays detailed error information.

Allow Retool IP addresses to access your data source

Certain resources use an allowlist of IP addresses to prevent unauthorized connections. Add Retool's IP addresses to your allowlist if necessary.

Each data source can use a different method for allowing remote connections. Refer to the data source's documentation to learn how you add allow IP addresses.

Verify your credentials or connection string is correct

For databases like PostgreSQL and MongoDB, Retool allows you to connect using traditional credentials (username, database, password, port) and a connection string.

Verify that your credentials are correct and that you're referencing the correct database.

The final part of a connection string (/mydb) references the database name. Ensure that your connection string references the correct database. If you copy a connection string from a console (like MongoDB Atlas), this may default to another database name.

Database or provider credentials

You must provide a database username and password when connecting using traditional credentials or with a connection string. These credentials are often not the same as those used to access your data source's web console.

Create a new database user specifically for connecting with Retool and use these credentials to create the resource.

SSL and certificates

Certain integrations support end-to-end encryption using SSL (e.g., MongoDB). This additional layer of security keeps your data safe and prevents threats like man-in-the-middle (MITM) attacks.

If SSL is available for a resource, Retool displays SSL on the resource connection page.

If your database uses a self-signed certificate instead of a publicly signed certificate, you must configure Retool to trust the custom certificate. Check Connect using SSL and then check Use a self-signed certificate.

Connect via SSH tunneling

If you cannot allow Retool's IP address or need to use data on a private network, you can create an SSH tunnel. SSH tunneling is not supported by all integrations.

Common error messages

Retool reports on any errors when connecting to a data source. The following errors occur if any provided information is invalid (e.g., username and password are incorrect) or if Retool is unable to connect to the data source (e.g., Retool IP addresses not added to an allowlist).

Error	Description
getaddrinfo ENOTFOUND	The hostname is not reachable. Verify the hostname details are correct, Retool is allowed to access it, or if it is behind a private network that requires SSH tunneling.
password authentication failed for user	The credentials are incorrect. Verify the credentials and try again.
database "" does not exist	The database does not exist. Verify the database details and try again.
connect ECONNREFUSED	The port is incorrect or Retool is not allowed to access the data source.