All Products
Search

This Product

    ApsaraDB for MongoDB:Troubleshoot connection and network issues

    Document Center

    ApsaraDB for MongoDB:Troubleshoot connection and network issues

    Last Updated:Jun 10, 2026

    Diagnose and fix connection failures for ApsaraDB for MongoDB instances. Start with Common errors for quick fixes, or follow Troubleshooting steps to systematically identify the root cause.

    Troubleshooting steps

    Step 1: Check network connectivity

    Troubleshooting method

    Test connectivity to the ApsaraDB for MongoDB instance with the following commands.

    • Run the ping <domain> command. For example, run ping dds-xxxx.mongodb.rds.aliyuncs.com.

      ping dds-xxx.mongodb.rds.aliyuncs.com
PING dds-xxx.mongodb.rds.aliyuncs.com (xxx): 56 data bytes
64 bytes from xxx: icmp_seq=0 ttl=90 time=7.698 ms
64 bytes from xxx: icmp_seq=1 ttl=90 time=7.085 ms
64 bytes from xxx: icmp_seq=2 ttl=90 time=11.006 ms
64 bytes from xxx: icmp_seq=3 ttl=90 time=12.154 ms
64 bytes from xxx: icmp_seq=4 ttl=90 time=9.149 ms

      This output confirms the client can reach the ApsaraDB for MongoDB instance.

    • Run the telnet <domain> <port> command. For example, run telnet dds-xxxx.mongodb.rds.aliyuncs.com 3717.

      root@mongotest:~# telnet xxx.mongodb.rds.aliyuncs.com 3717
Trying xxx...
Connected to xxx.mongodb.rds.aliyuncs.com.
Escape character is '^]'.

      This output confirms DNS resolution and port 3717 accessibility.

    Checklist

    If the network test fails, check the following items.

    Check the instance status. The instance must be in the Running state.

    Check the whitelist settings. The client's IP address must be added to the whitelist of the ApsaraDB for MongoDB instance.

    • How to check:

      Temporarily add 0.0.0.0/0 to the instance's whitelist. If you can connect to the instance after this change, the original whitelist settings were incorrect.

      Important

      The IP address 0.0.0.0/0 allows any device to access the ApsaraDB for MongoDB instance, which poses a security risk. Use this IP address for testing purposes only and remove it from the whitelist immediately after testing.

    • Solution:

      Add the correct client IP address to the whitelist. To find your client's public IP, check the FAQ.

    Check the network type and endpoint. Use the correct endpoint for your network type (private or public).

    You can log on to the ApsaraDB for MongoDB console and view the endpoints of the instance on the Database Connection page.

    Step 2: Authorization and authentication

    Verify the account name and password, and check for special characters in the password.

    • Verify that the provided account name and password are correct.

    • Change the password. If you need to change the password, see Reset password.

      If you change the password after connecting to the ApsaraDB for MongoDB instance by using Data Management Service (DMS), go to the DMS console, right-click the target instance, and then select Edit to log on again.

    • Special characters. When you use the MongoDB Shell or application code to connect to an ApsaraDB for MongoDB instance, you must escape any special characters such as !@#$%^&*()_+= in the account name or password. How do I resolve a connection failure that is caused by special characters in a username or password?.

    Check the authentication database. A database account must be authenticated against the database to which it belongs.

    How do I specify an authentication database in a connection?.

    Check the instance endpoint. For a replica set instance that requires write operations, we recommend that you connect by using the ConnectionString URI endpoint.

    • Symptom: The instance suddenly becomes inaccessible, even though the endpoint has not been changed.

    • Cause: Only the primary node can perform write operations. If your application was previously connected by using the endpoint of the primary node, a failover can change the connected node to a secondary node, which causes write operations to fail.

    • Solution:

      • For production environments, we recommend that your application connects to the database by using a ConnectionString URI. This way, if a node fails, read and write operations are unaffected by failover. For endpoint details, see the following topics:

      • Manually switch node roles. Promote the node that corresponds to the single-node endpoint to the primary node.

      Implement a reconnection mechanism and exception handling in your application to ensure automatic recovery from transient disconnections.

    Step 3: Other checks

    Check if the instance performance meets your business requirements.

    Check third-party tools.

    If a third-party tool, such as Navicat or Compass, cannot connect to your ApsaraDB for MongoDB instance, the issue might be caused by incorrect instance or tool settings. Follow these steps to troubleshoot:

    1. Test the connection by using the MongoDB Shell.

      We recommend that you use the MongoDB Shell to connect to the instance by using its high-availability ConnectionString URI.

    2. Troubleshoot the issue based on the test result.

      • Connection successful: The instance is accessible. The issue is likely caused by incorrect settings in the third-party tool. Check the tool's configuration.

      • Connection failed: If the MongoDB Shell cannot connect, the instance settings may be incorrect. Follow the steps in this topic to check the network connectivity, authorization, authentication, and other settings.

    Common errors

    Error message

    Cause and solution

    network error while attempting to run command 'isMaster' on host 'dds-xxxx.mongodb.rds.aliyuncs.com:3717' :exception: connect failed

    • Timed out after 3000ms while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}. exception=(com.mongodb.MongoSocketReadException: Prematurely reached end of stream)

    • Socket recv() errno:54 Connection reset by peer x.x.x.x:27017

    The instance may have reached its connection limit.

    Solution:

    1. Check whether connections are exhausted. How do I query the number of connections?.

    2. Optimize connection usage. What do I do if the number of connections to my instance reaches its limit?.

    MongoDB.Driver.MongoWaitQueueFullException: The wait queue for acquiring a connection to server xxx is full.

    The MongoDB driver wait queue is full, likely due to an undersized connection pool or high concurrency.

    Solution:

    1. Check the connection pool configuration in the application. Ensure the pool is appropriately sized. How do I limit the number of client connections?.

    2. If the issue persists, check whether connections to the ApsaraDB for MongoDB instance are exhausted:

      1. How do I query the number of connections?

      2. What do I do if the number of connections to my instance reaches its limit?

    (TooManyLogicalSessions) Unable to add session into the cache because the number of active sessions is too high.

    Excessive concurrent connections can exhaust available sessions.

    Solution:

    1. Troubleshoot the connection failure that is caused by exhausted connections.

      1. How do I query the number of connections?

      2. What do I do if the number of connections to my instance reaches its limit?

    2. If the number of connections is normal, check whether other performance metrics of the instance meet your business requirements.

      1. Use node monitoring to check resource usage, such as CPU and memory, to determine if the instance type meets your business requirements.

      2. If the instance type is too small for the workload, change the instance configuration during off-peak hours.

    • getaddrinfo failed.

    • No suitable servers found (`serverSelectionTryOnce` set).

    Verify that the instance endpoint is correct:

    • Failed to connect to 10.*.*.8:3717 after 5000 milliseconds, giving up.Error: couldn't connect to server 10.*.*.8:3717 (10.*.*.8), connection attempt failed

    • pymongo.errors.ServerSelectionTimeoutError: dds-xxxx.mongodb.rds.aliyuncs.com:3717: [Errno 113] No route to host,dds-xxxx.mongodb.rds.aliyuncs.com:3717

    • InvalidInstanceId.NotFound: The instance not in current vpc.

    An ECS instance fails to connect to an ApsaraDB for MongoDB instance over a private network.

    Solution:

    1. Check the whitelist settings. Make sure that the private IP address of the ECS instance is added to the whitelist of the ApsaraDB for MongoDB instance.

    2. Make sure that the ECS instance and the ApsaraDB for MongoDB instance can communicate with each other over the network.

      If the ECS instance and the ApsaraDB for MongoDB instance are in the same VPC, they can connect directly over the private network. If they are in different VPCs, use one of the following methods:

    org.springframework.data.mongodb.UncategorizedMongoDbException: Timeout while receiving message; nested exception is com.mongodb.MongoSocketReadTimeoutException: Timeout while receiving message

    • "errmsg": "not master", "code": 10107, "codeName": "NotMaster"

    • "errmsg": "not master", "code": 10107, "codeName": "NotWritablePrimary"

    • Time out after 30000ms while waiting for a server that matches writableServerSelector.

    • Command failed with error 10107 (NotWritablePrimary): 'not primary' on server xxx.

    • Explain's child command cannot run on this node. Are you explaining a write command on a secondary?

    • not master and slaveOk=false.

    • MongoNotPrimaryException: Command failed with error 10107 (NotMaster): 'not master' on server xxx.

    • reason: TopologyDescription { type: 'ReplicaSetNoPrimary',...}

    The node to which data is being written is not a primary node.

    Cause: Write operations can be performed only on the primary node. If your application was previously connected by using the endpoint of the primary node, a failover can change the connected node to a secondary node, which causes write operations to fail.

    Solution:

    • For production environments, we recommend that your application connects to the database by using a ConnectionString URI. This way, if a node fails, read and write operations are unaffected by failover. For endpoint details, see the following topics:

    • Manually switch node roles. Promote the node that corresponds to the single-node endpoint to the primary node.

    Implement a reconnection mechanism and exception handling in your application to ensure automatic recovery from transient disconnections.

    [Unauthorized] cloud instance error, disk locked, plz check and upgrade your disk quota,

    Exhausted disk space has locked the instance.

    Solution: Resolve instance locking or write failures caused by exhausted disk space.

    (AuthenticationFailed) Authentication failed.

    • !xxx@dds-xxx.mongodb.rds.aliyuncs.com: event not found

    The password of the database account contains special characters, such as !@#$%^&*()_+=.

    Solution: How do I resolve a connection failure that is caused by special characters in a username or password?.

    error getting cluster ID: (CommandNotFound) replSetGetConfig is forbidden by cloud provider for security reason

    ApsaraDB for MongoDB does not support replSetGetConfig. Limits on commands in ApsaraDB for MongoDB.

    FAQ

    Querying connections

    The maximum number of connections varies by instance type.

    Note

    The connection limit applies per node. For example, a three-node replica set instance with 1 vCPU and 2 GB memory allows up to 500 connections on both the primary node and each secondary node. The hidden node does not serve traffic.

    Console

    1. Go to the ApsaraDB for MongoDB Replica Set Instances page or the ApsaraDB for MongoDB Sharded Cluster Instances page. In the top navigation bar, select a region. Then, click the ID of the target instance.

    2. In the left-side navigation pane, click Monitoring Information.

    3. On the Monitoring Information page, view the Connections information for the instance.

      If the instance is a sharded cluster instance, you must select the Mongos that your service currently uses in the upper-right corner of the page.

    Command

    1. Connect to the instance by using the MongoDB Shell.

    2. View the number of connections.

      Run the db.serverStatus().connections command.

      mgset-123456:PRIMARY> db.serverStatus().connections
{
        "current" : 1,
        "available" : 999,
        "internal_current" : 10,
        "internal_available" : 990,
        "totalCreated" : 632
}

      Parameter description:

      • "current": the number of established connections.

      • "available": the number of available connections.

    3. Query the current connection sources.

      1. Switch to the admin database. 

        use admin

      2. Run the db.runCommand({currentOp: 1, $all: true}) command.

        mgset-123456:PRIMARY> db.runCommand({currentOp: 1, $all:[{"active" : true}]})

      Analyze the output to identify the source IP and connection count per client. db.currentOp().

    Limiting client connections

    Append &maxPoolSize=<integer> to the Connection String URI to limit the pool size. The following example connects with the MongoDB Shell and sets the pool to 10 connections (account: test, auth database: admin):

    mongosh "mongodb://test:****@dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-6108****&maxPoolSize=10"
    Note

    To limit the pool size for other languages, check the MongoDB Drivers documentation.

    Handling connection limit

    You can restart the instance, its components, or nodes to temporarily release all connections.

    Important

    When you restart an instance, its nodes are restarted in sequence. Each node experiences a transient disconnection of about 30 seconds. If the instance contains a large number of collections (more than 10,000), the disconnection may last longer. Before you restart the instance, plan accordingly and ensure that your application has a reconnection mechanism.

    After restarting, make the following adjustments to prevent recurrence:

    Special characters in credentials

    Connections fail if the account name or password in the connection string contains unescaped special characters such as !@#$%^&*()_+=.

    Solution: Escape the special characters in the connection string. The following table describes the encoding rules.

    ! : %21
@ : %40
# : %23
$ : %24
% : %25
^ : %5e
& : %26
* : %2a
( : %28
) : %29
_ : %5f
+ : %2b
= : %3d

    Example: If the password is ab@#c, you must escape the special characters in the connection string. The escaped password is ab%40%23c.

    Specifying an authentication database

    A database account must be authenticated against the database where it was created.

    Assume that the username and password are both test, and the test account belongs to the testdb database.

    High-availability endpoint

    In a ConnectionString URI or read-only ConnectionString URI, set authSource to the database where the account was created. If omitted, <database> in the URI is used for authentication.

    Examples:

    • After the test account is authenticated against the testdb database, the instance switches to the <database> database.

    mongosh "mongodb://test:test@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/<database>?replicaSet=<replicaSet_value>&authSource=testdb"

    • After the test account is authenticated against the testdb database, the instance switches to the testdb database.

    mongosh "mongodb://test:test@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/testdb?replicaSet=<replicaSet_value>"

    Single-node endpoint

    You can run one of the following commands to log on:

    mongosh --host $myhost --port $myport -u test -p test --authenticationDatabase testdb

    or

        mongosh --host $myhost --port $myport
    mongo> use testdb
    mongo> db.auth("test", "test")

    Endpoint parameter details: Connect to a replica set instance and Connect to a sharded cluster instance.

    Supported client languages

    ApsaraDB for MongoDB is fully compatible with MongoDB and supports all official MongoDB clients.

    Supported languages include C, C++, C#, Java, Node.js, Python, PHP, and Perl (official documentation).

    For sample code, see the following topics:

    Note

    To ensure proper authentication when you connect to an ApsaraDB for MongoDB instance, use a MongoDB driver of version 3.0 or later.

    Password-free access

    ApsaraDB for MongoDB no longer supports enabling password-free access over a VPC.

    If password-free access is already enabled, you can permanently disable it. Disable password-free access over a private network.

    Mongo Shell on Windows

    • Download and install the MongoDB Shell from the MongoDB Shell Download page.

    • Use the MongoDB Shell.

      • Open the Command Prompt application.

      • Connect to the ApsaraDB for MongoDB instance.

        Example:

        mongosh "mongodb://test:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-6108****"

        Connection string parameters: Connect to a replica set instance and Connect to a sharded cluster instance.

    Common connection scenarios