FAQ: MongoDB Diagnostics

This document provides answers to common diagnostic questions and issues.

If you don’t find the answer you’re looking for, check the complete list of FAQs or post your question to the MongoDB Community .

Where can I find information about a mongod process that stopped running unexpectedly?

If mongod shuts down unexpectedly on a UNIX or UNIX-based platform, and if mongod fails to log a shutdown or error message, then check your system logs for messages pertaining to MongoDB. For example, for logs located in /var/log/messages, use the following commands:

sudo grep mongod /var/log/messages
sudo grep score /var/log/messages

Does TCP keepalive time affect MongoDB Deployments?

If you experience network timeouts or socket errors in communication between clients and servers, or between members of a sharded cluster or replica set, check the TCP keepalive value for the affected systems.

Many operating systems set this value to 7200 seconds (two hours) by default. For MongoDB, you will generally experience better results with a shorter keepalive value, on the order of 120 seconds (two minutes).

If your MongoDB deployment experiences keepalive-related issues, you must alter the keepalive value on all affected systems. This includes all machines running mongod or mongos processes and all machines hosting client processes that connect to MongoDB.

Adjusting the TCP keepalive value:

  • To view the keepalive setting on Linux, use one of the following commands:

    sysctl net.ipv4.tcp_keepalive_time


    cat /proc/sys/net/ipv4/tcp_keepalive_time

    The value is measured in seconds.


    Although the setting name includes ipv4, the tcp_keepalive_time value applies to both IPv4 and IPv6.

  • To change the tcp_keepalive_time value, you can use one of the following commands, supplying a <value> in seconds:

    sudo sysctl -w net.ipv4.tcp_keepalive_time=<value>


    echo <value> | sudo tee /proc/sys/net/ipv4/tcp_keepalive_time

    These operations do not persist across system reboots. To persist the setting, add the following line to /etc/sysctl.conf, supplying a <value> in seconds, and reboot the machine:

    net.ipv4.tcp_keepalive_time = <value>

    Keepalive values greater than 300 seconds, (5 minutes) will be overridden on mongod and mongos sockets and set to 300 seconds.

  • To view the keepalive setting on Windows, issue the following command:

    reg query HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters /v KeepAliveTime

    The registry value is not present by default. The system default, used if the value is absent, is 7200000 milliseconds or 0x6ddd00 in hexadecimal.

  • To change the KeepAliveTime value, use the following command in an Administrator Command Prompt, where <value> is expressed in hexadecimal (e.g. 120000 is 0x1d4c0):

    reg add HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\ /t REG_DWORD /v KeepAliveTime /d <value>

    Windows users should consider the Windows Server Technet Article on KeepAliveTime for more information on setting keepalive for MongoDB deployments on Windows systems. Keepalive values greater than or equal to 600000 milliseconds (10 minutes) will be ignored by mongod and mongos.

  • To view the keepalive setting on macOS, issue the following command:

    sysctl net.inet.tcp.keepidle

    The value is measured in milliseconds.

  • To change the net.inet.tcp.keepidle value, you can use the following command, supplying a <value> in milliseconds:

    sudo sysctl net.inet.tcp.keepidle=<value>

    This operation does not persist across system reboots, and must be set each time your system reboots. See your operating system’s documentation for instructions on setting this value persistently. Keepalive values greater than or equal to 600000 milliseconds (10 minutes) will be ignored by mongod and mongos.


    In macOS 10.15 Catalina, Apple no longer allows for configuration of the net.inet.tcp.keepidle option.

You will need to restart mongod and mongos processes for new system-wide keepalive settings to take effect.

Why does MongoDB log so many “Connection Accepted” events?

If you see a very large number of connection and re-connection messages in your MongoDB log, then clients are frequently connecting and disconnecting to the MongoDB server. This is normal behavior for applications that do not use request pooling, such as CGI. Consider using FastCGI, an Apache Module, or some other kind of persistent application server to decrease the connection overhead.

If these connections do not impact your performance you can use the run-time quiet option or the command-line option --quiet to suppress these messages from the log.

What tools are available for monitoring MongoDB?

The MongoDB Cloud Manager and Ops Manager, an on-premise solution available in MongoDB Enterprise Advanced include monitoring functionality, which collects data from running MongoDB deployments and provides visualization and alerts based on that data.

For more information, see also the MongoDB Cloud Manager documentation and Ops Manager documentation .

A full list of third-party tools is available as part of the Monitoring for MongoDB documentation.

Memory Diagnostics for the MMAPv1 Storage Engine

Do I need to configure swap space?

Always configure systems to have swap space. Without swap, your system may not be reliant in some situations with extreme memory constraints, memory leaks, or multiple programs using the same memory. Think of the swap space as something like a steam release valve that allows the system to release extra pressure without affecting the overall functioning of the system.

Nevertheless, systems running MongoDB do not need swap for routine operation. Database files are memory-mapped and should constitute most of your MongoDB memory use. Therefore, it is unlikely that mongod will ever use any swap space in normal operation. The operating system will release memory from the memory mapped files without needing swap and MongoDB can write data to the data files without needing the swap system.

What is a “working set”?

The working set is the portion of your data that clients access most often.

Must my working set size fit RAM?

Your working set should stay in memory to achieve good performance. Otherwise many random disk IO’s will occur, and unless you are using SSD, this can be quite slow.

One area to watch specifically in managing the size of your working set is index access patterns. If you are inserting into indexes at random locations (as would happen with id’s that are randomly generated by hashes), you will continually be updating the whole index. If instead you are able to create your id’s in approximately ascending order (for example, day concatenated with a random id), all the updates will occur at the right side of the b-tree and the working set size for index pages will be much smaller.

It is fine if databases and thus virtual size are much larger than RAM.

How do I calculate how much RAM I need for my application?

The amount of RAM you need depends on several factors, including but not limited to:

  • The relationship between database storage and working set.
  • The operating system’s cache strategy for LRU (Least Recently Used)
  • The impact of journaling
  • The number or rate of page faults and other MongoDB Cloud Manager gauges to detect when you need more RAM
  • Each database connection thread will need up to 1 MB of RAM.

MongoDB defers to the operating system when loading data into memory from disk. It simply memory maps all its data files and relies on the operating system to cache data. The OS typically evicts the least-recently-used data from RAM when it runs low on memory. For example if clients access indexes more frequently than documents, then indexes will more likely stay in RAM, but it depends on your particular usage.

To calculate how much RAM you need, you must calculate your working set size, or the portion of your data th