Why is FreeableMemory low on my Amazon DocumentDB cluster?

Resolution

How Amazon DocumentDB allocates instance memory

FreeableMemory reports the amount of available random access memory (RAM), in bytes, on an Amazon DocumentDB instance. Amazon DocumentDB utilizes instance memory for three purposes:

• Buffer cache - stores the most recently accessed data and indexes in memory to reduce I/O requests and improve performance. Amazon DocumentDB deliberately uses around two-thirds of an instance's RAM to cache your working set, which are your data pages and index pages that your queries actively touch
• Engine execution and management - memory reserved for the Amazon DocumentDB database engine's internal processes such as health checks, replication and background maintenance.
• Freeable memory - the remaining unallocated memory reported by the operating system will be used per connections for query processing (sorts, aggregations, hash joins) and operating-system page cache.

Memory allocation of Buffer Cache and for internal processes occurs when the database is turned on and thus, you will see its proportional dip in the FreeableMemory metric. Rest of the memory will be managed on a per connection basis based on its requirements of query processing.

Why FreeableMemory drops

1. Database connections

Each connection to a DocumentDB instance allocates a fixed amount of memory for session state, authentication context, and internal buffers. Under normal operating conditions, this allocation is predictable and proportional to the number of active clients. However, a misconfigured connection pool, uncontrolled retry logic that opens new connections on each failure, or a deployment event that introduces many application instances at once can produce a connection storm. When hundreds or thousands of sessions are established in a short period, the cumulative memory allocation can significantly reduce FreeableMemory. To prevent this, enforce a maximum pool size on every application client and monitor the DatabaseConnectionsMax and DatabaseConnectionsActiveMax CloudWatch metrics to understand peak connection behaviour within each one-minute window. If connection counts are rising while query latency and DatabaseCursorsTimedOut remain flat, the memory is being consumed by idle sessions rather than active work. In this scenario, tightening pool settings, reducing idle connection timeouts, or consolidating application instances behind a connection-aware proxy will help recover memory.

2. Cursors

When a query returns more results than fit in a single network batch, DocumentDB holds an open cursor on the server. This cursor maintains the intermediate result set, or a pointer into it, in memory until the client issues a getMore command to retrieve the next batch. If the client never fetches subsequent batches due to application bugs, network interruptions, or neglecting to close the cursor, the cursor remains idle and continues to consume memory. Because idle cursors generate no CPU or I/O overhead, they do not appear in common performance metrics, making cursor leaks particularly difficult to detect. Monitor the DatabaseCursors and DatabaseCursorsMax CloudWatch metrics to identify cursor accumulation before it degrades FreeableMemory. On the application side, always use try/finally blocks or equivalent resource management patterns to ensure cursors are closed after use. Additionally, configure a reasonable noCursorTimeout policy so the server can reclaim resources from abandoned cursors automatically. If you observe a sudden increase in open cursors without a corresponding rise in client request rate, list the cursors, investigate recent application deployments or client-library upgrades that may have altered batch-fetching behaviour.

3. High-concurrency batch writes

Large-scale batchInsert or batchUpdate operations require DocumentDB to allocate memory for document parsing, BSON validation, index maintenance, and write-ahead-log buffering on the primary instance. When multiple application workers submit these operations concurrently, the combined memory demand can exceed the available FreeableMemory, particularly if individual batch payloads contain thousands of documents per request. The result is a rapid and steep decline in FreeableMemory that can push the instance into the throttling zone. To mitigate this, limit write concurrency at the application tier by capping the number of parallel writer threads or using a semaphore to serialize batch submissions. Reducing batch sizes also helps distribute memory demand over time. If the workload genuinely requires sustained high-throughput ingestion, scale up to a larger instance class that provides additional RAM headroom. Monitor OpcountersInsert, OpcountersUpdate, DocumentsInserted and DocumentsUpdated alongside FreeableMemory to correlate write volume spikes with memory consumption.

Is low FreeableMemory a concern?

It depends on the how low your FreeableMemory. As per our documented threshold, if your FreeableMemory metric frequently dips below 10% of the total instance memory and swap usage is growing, consider scaling up your instances.

What DocumentDB does under real memory pressure

Amazon DocumentDB safeguards resources for critical processes such as health checks. When an instance experiences high memory pressure, Amazon DocumentDB throttles requests. Some operations might be queued until the memory pressure subsides. If memory pressure continues, queued operations might time out.

Applications may also see error code 39, which DocumentDB uses for operations canceled because they exceeded maxTimeMS, ran too long, or exceeded available memory. Because the code covers several conditions, treat it as corroborating evidence alongside the LowMem* metrics rather than as proof of memory exhaustion.

Sustained pressure can additionally drive SwapUsage above zero and, in extreme cases, lead to instance instability. AWS documents throttling and timeouts as the governed response; swap growth and restarts are downstream consequences rather than a documented escalation sequence.

FreeableMemory in DocumentDB Serverless

The metric means something different on serverless instances as it represents the amount of unused memory that is available when the DocumentDB serverless instance is scaled to its maximum capacity. Each DCU is a combination of approximately 2 gibibytes (GiB) of memory, corresponding CPU, and networking. Thus, this metric doesn't approach zero until the instance is scaled up as high as it can.

It signals proximity to your configured ceiling, not under-provisioning during a scaling ramp. Monitor ServerlessDatabaseCapacity (current DCUs) and DCUUtilization (percentage of maximum DCU) to get deeper insights when serverless configuration is used. If DCUUtilization or FreeableMemory approaches its usage limits, raise the maximum DCU setting.