How to Fix MongoDB Replica Set Connection String Errors

In this tutorial, you'll learn about How to Fix MongoDB Replica Set Connection String Errors. We cover key concepts, practical examples, and best practices.

The Problem

Your application can't connect to a MongoDB replica set:

MongoNetworkError: getaddrinfo ENOTFOUND mongo1
MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

Or the driver warning: The options.replicasetandoptions.routerselectionconfigsandoptions.serverselectionconfigs are deprecated in the URI. MongoDB replica set connection strings require specific formatting — wrong hostnames, missing replica set names, or incorrect ordering cause connection failures. The driver must discover all replica set members, and a single wrong hostname can prevent the entire connection.

Quick Fix

1. Verify the replica set connection string format

mongodb://mongo1:27017,mongo2:27018,mongo3:27019/mydb?replicaSet=rs0

The format is: <a href="/databases/mongodb/">mongodb</a>://host1:port1,host2:port2,.../database?replicaSet=name. The replicaSet parameter is required for replica set connections. Without it, the driver connects to a single node and can't failover.

2. Check the replica set name matches

// In mongosh
rs.status();

Expected output:

{
  set: "rs0",
  members: [
    { _id: 0, name: "mongo1:27017", stateStr: "PRIMARY" },
    { _id: 1, name: "mongo2:27018", stateStr: "SECONDARY" }
  ]
}

The set value must match the replicaSet=rs0 parameter in your connection string.

3. Test connectivity to each host

# Test from the application host
nc -zv mongo1 27017
nc -zv mongo2 27018
nc -zv mongo3 27019

The application must be able to reach ALL replica set members, not just the primary. If even one host is unreachable, the driver may fail to establish the topology.

4. Use the correct hosts from the application's perspective

MongoDB replica set members advertise their hostnames (member.name). If your containers use Docker internal hostnames but your application resolves them differently, the connection fails. Override with /etc/hosts or use Docker service names.

5. Include authentication in the connection string

mongodb://appuser:password@mongo1:27017,mongo2:27018/mydb?replicaSet=rs0&authSource=admin

authSource=admin specifies the database where the user is defined. Without it, the driver authenticates against mydb, which fails if the user was created in admin.

6. Use directConnection for single-node replica sets in development

mongodb://localhost:27017/mydb?replicaSet=rs0&directConnection=true

In development, you might run a single-node replica set. The directConnection=true flag tells the driver to connect to the specified host without attempting to discover other members.

7. Set appropriate timeouts

mongodb://mongo1:27017,mongo2:27018/mydb?replicaSet=rs0&serverSelectionTimeoutMS=5000&connectTimeoutMS=10000

serverSelectionTimeoutMS controls how long the driver tries to find a suitable server before failing. Increase this for slow networks; decrease it to fail fast in CI.

8. Test the connection string with mongosh

mongosh "mongodb://appuser:password@mongo1:27017,mongo2:27018/mydb?replicaSet=rs0"

Expected output:

Current Mongosh Log ID: ...
Connecting to: mongodb://...?replicaSet=rs0
Connected to replica set rs0 with 3 members

Testing with mongosh isolates connection issues before involving application code.

Prevention

• Verify rs.status().set matches the replicaSet parameter in your URI
• Ensure all replica set members are resolvable from the application host
• Use environment-specific connection strings (never hardcode)
• Always specify authSource when using authentication
• Test with mongosh "<a href="/databases/mongodb/">mongodb</a>://..." before configuring the application
• Use directConnection=true only in development — never in production