DocsICP FilingConsole
Documentation
Home Page ApsaraDB for MongoDB Support FAQ Troubleshoot connection and network issues

Troubleshoot connection and network issues

Updated at:
Copy as MD
Product
My Favorites

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:

    • (Recommended) Use the Connection Diagnosis feature of ApsaraDB for MongoDB to check IP connectivity. For instructions on how to run the check and resolve issues, see Connection diagnosis.

    • 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).

Log on to the ApsaraDB for MongoDB console and view the endpoints 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 reconnection logic and exception handling in your application to recover automatically 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 may stem from 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.

    ECS and ApsaraDB for MongoDB instances in the same VPC 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 reconnection logic and exception handling in your application to recover automatically 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 ConnectionString URI to limit the pool size. The following example 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, take the following steps 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 !@#$%^&*()_+=.

Escape the special characters in the connection string. The following table lists 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.

Connection fails after the readPreference parameter is specified in mongosh

In a shell, the ampersand (&) runs a command in the background. As a result, the connection string is truncated and the subsequent readPreference parameter cannot be recognized. Enclose the entire connection string in quotation marks. The following sample command provides an example:

mongosh "mongodb://root:****@dds-bp10a572fae7a****.mongodb.rds.aliyuncs.com:3717,dds-bp10a572fae7a****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-9202****&readPreference=secondary"

Common connection scenarios

Previous：Purchase and paymentNext：Primary/secondary switchover