MongoDB connection error

Updated 11 October 2026

Short answer

If you use MongoDB Atlas, the most common cause is that your app server's IP address isn't on the cluster's IP access list, so Atlas silently refuses it and the app times out. This often happens after deploying to a new host, or on platforms whose IP addresses change. Other causes: a wrong connection string or password, special characters in the password that aren't percent-encoded, or a paused cluster.

What's the problem

Your app fails to start or loses access to its data with a MongoDB error: a server selection or connection timeout, a refused connection, or an authentication failure.

Why it happens

  • IP not allowed: the app's server isn't on the Atlas IP access list.
  • Wrong connection string: a typo, the wrong cluster, or a missing database name.
  • Password problems: wrong password, or special characters (@, :, /) not percent-encoded in the connection string.
  • The cluster is paused. Atlas pauses idle free clusters after 30 days with no connections.
  • DNS or network issues reaching mongodb+srv addresses.
  • Self-hosted MongoDB isn't running or only listens on localhost.

How to fix it

  1. Read the full error. A timeout usually means the network or the access list; an authentication failure means the username or password.
  2. Add your app server's IP address to the Atlas IP access list. For platforms with changing IPs, check the platform's guidance.
  3. Check the connection string in your live environment variables against the one Atlas gives you.
  4. Percent-encode special characters in the username or password, such as @, : and /.
  5. Check the cluster isn't paused in the Atlas dashboard.
  6. For self-hosted MongoDB, check it's running and its bindIp allows your app.

What Preventionlabs checks

One click runs the full report on your domain. For this problem it shows whether your site loads, how fast, and where its redirects go; uptime checked every 5 minutes, with an email when the site goes down and when it is back. With Cloudflare connected, it also shows which pages returned server errors (5xx) to visitors, and when; recent deploys and account changes, with their times. It can't connect to your database, so the database error itself is in your host's or database provider's logs.

Run your free report

Your first report is free, no card needed. Then A$50 a month, up to 10 domains. Read-only: it never changes anything.

Sources

  1. MongoDB: Configure IP Access List Entriesofficial docsAtlas only allows client connections to the cluster from entries in the project's IP access list.
  2. MongoDB: Troubleshoot Connection Issuesofficial docsBefore connecting to your Atlas cluster, check that you added your host's IP address to the IP access list for your cluster's project.
  3. MongoDB: Connection String Formatsofficial docsIf the username or password includes the following characters, those characters must be converted using percent encoding: $ : / ? # [ ] @
  4. MongoDB: Troubleshoot Connection Issuesofficial docsAtlas automatically pauses idle Free clusters (formerly known as M0 ) after 30 days with no connections.

Related

Database connection error Your app can't reach its database: the database is stopped, the address or password is wrong, or a firewall is blocking it. Check them in that order. Database timeout A query or connection took longer than allowed: usually a slow query on a big table, a missing index, locked rows, or an overloaded database. Backend down: server unreachable Check whether the backend answers at all: no response points to the server, DNS or firewall; an error code points to the app or its database. API not working Look at the status code and response body the API returns: 4xx means the request is wrong (login, data, limits); 5xx means the API's server failed.

Preventionlabs is independent and not affiliated with MongoDB. Product names are used only to describe the problem.

← All of Database