Docs Menu

Docs HomeMongoDB Atlas

Test Failover

On this page

  • Test Failover Process
  • Test Failover Using the Atlas UI
  • Test Failover Using the API
  • Verify the Failover
  • Troubleshoot Failover Issues


This feature is not available for M0 free clusters, M2, and M5 clusters. To learn more about which features are unavailable, see Atlas M0 (Free Cluster), M2, and M5 Limitations.

Atlas conducts replica set elections when it makes configuration changes, such as patch updates, scaling events, and when failures occur. Your applications should handle replica set elections without any downtime. To learn how to build a resilient application, see Build a Resilient Application with MongoDB Atlas.

You can enable retryable writes by adding retryWrites=true to your Atlas URI connection string. To learn more, see Retryable Writes.

You can use the Atlas UI and API to test the failure of the replica set primary in your Atlas cluster and observe how your application handles a replica set failover.

When you submit a request to test failover using the Atlas UI or API, Atlas simulates a failover event. During this process:

  1. Atlas shuts down the current primary.

  2. The members of the replica set hold an election to choose which of the secondaries will become the new primary.

  3. Atlas brings the original primary back to the replica set as a secondary. When the old primary rejoins the replica set, it will sync with the new primary to catch up any writes that occurred during its downtime.

The following statements describe Atlas behavior during rollovers and when testing failover in sharded clusters:

To perform a Test Failover in the Atlas UI:

  1. Log in to the Atlas UI.

  2. Click Database.

  3. For the cluster you wish to perform failover testing, click the ... button.

  4. Click Test Outage.

  5. On the Test Outage modal, click the Primary Failover tab. Atlas displays the steps that it takes to simulate a failover event. To learn more, see Test Failover Process.

  6. Click Restart Primary to begin the test. Atlas displays the results of your simulated failover process in the Test Failover modal.

You can use the Test Failover API endpoint to simulate a failover event. To learn more about the failover process, see Test Failover Process.

To verify that the failover is successful:

  1. Log in to the Atlas UI and click Database.

  2. Click the name of the cluster for which you performed the failover test.

  3. Observe the following changes in the list of nodes in the Overview tab:

    • The original PRIMARY node is now a SECONDARY node.

    • A former SECONDARY node is now the PRIMARY node.

If your application doesn't handle the failover gracefully, ensure the following:

  • The connection string includes all members of the replica set.

  • You are using the latest version of the driver.

  • You have implemented appropriate retry logic in your application.

←  Simulate a Failover or OutageTest Outage →
Share Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.