What the error looks like
The reason after it tells you which connectivity problem you have:
MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017
at ... (mongodb/lib/sdam/topology.js)
# Atlas / DNS variants:
MongooseServerSelectionError: getaddrinfo ENOTFOUND cluster0.xxxx.mongodb.net
MongooseServerSelectionError: connection timed outECONNREFUSED = something refused the connection (not running, wrong host/port). ENOTFOUND = DNS could not resolve the cluster host. timed out = often a firewall or Atlas allowlist silently dropping packets.
Why it happens
Mongo not running / wrong host
No mongod at that host:port, or the connection string points somewhere wrong.
localhost inside Docker
localhost in a container is the container itself - use the Compose service name as the host.
Atlas IP allowlist
Your server's IP is not in Atlas Network Access, so the connection is blocked.
Bad SRV / connection string
A wrong mongodb+srv host, missing TLS, or DNS that cannot resolve the cluster.
Diagnose it in three steps
Is MongoDB reachable?
nc -zv 127.0.0.1 27017 # local
mongosh "mongodb+srv://user:[email protected]/db" # AtlasFor Atlas, check Network Access
# In Atlas: Network Access -> add your server's public IP.
# Confirm the server IP:
curl -s ifconfig.meIn Docker, use the service name
# app connects to host 'mongo' (the compose service), not localhost
MONGO_URI=mongodb://mongo:27017/myappMake Mongo reachable, then connect with sane timeouts
Ensure MongoDB is running and reachable from the app - the right host (a service name in Docker), the IP allowlisted in Atlas, and the correct connection string. Then set a sensible selection timeout so failures are fast and clear.
// Mongoose with explicit options
mongoose.connect(process.env.MONGO_URI, {
serverSelectionTimeoutMS: 5000, // fail fast with a clear error
});
# Docker compose - app waits for and points at the mongo service
MONGO_URI=mongodb://mongo:27017/myapp
# Atlas - add the server IP under Network Access (not 0.0.0.0/0 in prod)If the app starts before Mongo is ready, add a short connection retry, or order startup so the database is reachable before the app accepts traffic.
Order startup, health-check the database
An app that connects before its database is reachable is a startup-ordering problem. On your own servers, Infraveil health-checks dependencies and coordinates how services start, so the app does not go live before MongoDB is reachable - and connection failures surface with context, with configured, bounded recovery automation and selected operational records.
Frequently asked questions
What does MongooseServerSelectionError mean?
The driver could not find or reach a suitable MongoDB server within the serverSelectionTimeoutMS window - a connectivity problem (unreachable host/port, DNS failure, or a blocked IP), not a query problem.
Why connect ECONNREFUSED 127.0.0.1:27017?
Nothing is listening there: Mongo is not running locally, or inside Docker you used localhost, which is the app container itself. Use the Compose service name as the host, e.g. mongodb://mongo:27017.
Why does Atlas time out from my server but work locally?
Your server's public IP is not in the Atlas Network Access allowlist. Add it under Network Access. Use 0.0.0.0/0 only for short-lived testing, never in production.
How do I connect to MongoDB from Docker?
Use the Compose service name as the host - mongodb://mongo:27017/db - not localhost, which inside a container points at the container itself rather than the database.
Client-side, no signup — they run in your browser.