Write-Blocking

Write-Blocking and Intelligent Workload Management

Cluster write-blocking behavior is part of Intelligent Workload Management (IWM) in MongoDB Atlas. IWM is a dynamic resource manager that enables real-time workload monitoring and automated safeguards to maintain high availability under load.

Write-Blocking Considerations

Write-blocking behavior has the following considerations:

• Atlas currently blocks writes to the primary node on replica sets (non-sharded clusters) on dedicated clusters running MongoDB 8.0+.

• Atlas doesn't block writes on free and Flex clusters.

• Atlas monitors disk utilization on the primary node only. Atlas doesn't monitor disk utilization on secondary, read-only, search, or analytics nodes.

How Atlas Blocks Writes to the Primary Node

To block writes, Atlas uses the following process:

• When the primary node's free disk space exceeds write-blocking policy thresholds, Atlas blocks writes to the primary node.

  Even when the MongoDB database is not accepting writes, the cluster remains available for reads. You can read from the primary and secondary nodes as normal.

• When Atlas blocks writes, it sends the following alert: Writes have been blocked on your cluster due to critically low disk space. The activity feed reflects this alert.

  The top of the cluster page in the Atlas UI shows a banner that states: "To maintain read availability during critically high disk utilization, Atlas has blocked writes to the following clusters: <clusterName>. Increase disk space or enable storage auto-scaling to unblock writes."

• When free disk space increases 50% over the blocking threshold, Atlas unblocks writes to the primary node. When Atlas unblocks writes, you receive this alert: Writes have been unblocked on your cluster.

  The activity feed then reflects this alert. No further action is needed. To avoid write-blocking behavior in the future, consider increasing cluster storage.

• If you manually increase the disk size of the cluster or enable storage auto-scaling, Atlas automatically adjusts the write-blocking thresholds based on the new disk size.

Write-Blocking Prevention

To prevent write-blocking behavior from occurring and bring the cluster below the Atlas write-blocking policy thresholds, we recommend that you:

• Enable storage auto-scaling, which automatically scales your cluster storage when disk utilization exceeds 90% and ensures consistent workload availability and performance.

  To enable storage auto-scaling in the Atlas UI, navigate to the Cluster Tier menu and check the Storage Scaling checkbox in the Auto-scale section.

  • For all new clusters that you create in the Atlas UI, Atlas enables storage auto-scaling by default.

  • If you create clusters with the API, cluster auto-scaling isn't selected by default and you must explicitly enable it, using the options in the autoScaling object of the Update One Cluster in One Project endpoint.

• If you choose to opt out of storage auto-scaling and your disk utilization is close to 90%, you can release existing disk space before Atlas activates write-blocking behavior on your cluster:

  • Remove unused data to free up disk space. Delete the indexes, or delete collections or individual documents.

  • Use the autoCompact command on each dedicated cluster node to compact disk space.

Write-Blocking Policy Threshold Parameters

Atlas uses the following write-blocking thresholds to accommodate disk utilization scenarios with high write volume:

The thresholds are not configurable. If the disk size increases due to auto-scaling, or if you manually increase the disk size, Atlas automatically adjusts the thresholds based on cluster's disk size.

Once write-blocking behavior is active in your cluster, you:

• Can increase cluster storage manually from the Edit Cluster page or enable storage auto-scaling in the Atlas UI to avoid any future write-blocking behavior.

• Cannot delete indexes or collections because Atlas blocks operations that require writing to the database. To delete indexes and collections, increase the cluster storage.

Write-Blocking and Storage Auto-Scaling

Atlas blocks writes when free disk space on the primary node reaches approximately 96% of total disk size, with the caveats for small and large disks noted in the write-blocking policy thresholds.

By comparison, auto-scaling triggers when disk utilization reaches 90% of total disk size. This means that:

• If you enable auto-scaling, your cluster has the opportunity to scale up before write-blocking behavior activates.

• If you disable auto-scaling, you must monitor disk utilization and take action to prevent write-blocking behavior from activating.

Write-Blocking Troubleshooting

When Atlas blocks writes to the cluster, the following actions occur:

• The top of the cluster page in the Atlas UI shows a banner indicating that writes have been blocked. See How Atlas Blocks Writes to the Primary Node.

• Atlas issues write-blocking alerts that you can resolve by increasing cluster storage. See also Fix Storage Issues.

• The project's Activity Feed reflects these alerts.

• Atlas logs return a MongoServerError similar to the following: User writes blocked, reason: DiskUseThresholdExceeded.

• The userWriteBlockMode parameter in serverStatus command reflects the cluster's current write-blocking status.

Unblocking Writes

Atlas unblocks writes when free disk space increases 50% over the blocking threshold. The extra buffer to unblock writes ensures that:

• Atlas doesn't enable and disable write-blocking behavior in quick succession.

• The cluster remains in a good state as it begins accepting writes again.

For the exact parameters, see write-blocking policy thresholds.