Introduction
Magento 2 includes a built-in maintenance mode that allows store owners and developers to temporarily restrict public access to their online store during upgrades, security patch installations, extension updates, database migrations, or server maintenance. This helps prevent customers from encountering broken pages, checkout issues, or unexpected errors while critical changes are being made.
When maintenance mode is enabled, visitors are shown a maintenance page instead of the storefront, ensuring a professional user experience during downtime. Magento 2 also allows specific IP addresses to bypass maintenance mode, enabling administrators and developers to test changes before the site is made live again.
In this guide, you’ll learn how to enable and disable maintenance mode in Magento 2, whitelist IP addresses, customize the maintenance page, and troubleshoot common maintenance mode issues.
Enabling Maintenance Mode in Magento
Magento 2 provides a built-in maintenance mode that temporarily restricts customer access to your store while updates, deployments, or maintenance activities are being performed. This helps prevent visitors from encountering errors, broken functionality, or incomplete updates.
To enable maintenance mode, navigate to your Magento 2 root directory and run:
php bin/magento maintenance:enable
Once enabled, visitors will see a 503 Service Unavailable maintenance page instead of the storefront.
Check Maintenance Mode Status
To verify whether maintenance mode is active, run:
php bin/magento maintenance:status
Expected output:
Maintenance mode is active.
Allowing Specific IPs to Access the Store
By default, maintenance mode blocks access to all visitors. However, Magento 2 allows you to whitelist specific IP addresses so that developers, administrators, or QA teams can continue accessing the store during maintenance.
Allow a Single IP Address
php bin/magento maintenance:allow-ips <your-ip-address>
Example:
php bin/magento maintenance:allow-ips 192.168.1.100
Allow Multiple IP Addresses
php bin/magento maintenance:allow-ips 192.168.1.100 192.168.1.101
Verify Allowed IP Addresses
Run the following command:
php bin/magento maintenance:status
Example output:
Maintenance mode is active. Allowed IPs: 192.168.1.100, 192.168.1.101
Remove All Allowed IP Addresses
To remove all whitelisted IPs and restrict access to everyone, run:
php bin/magento maintenance:allow-ips --none
Customizing the Magento Maintenance Page
- Magento’s default maintenance page is located at:
- pub/errors/default/503.phtml
- To create a custom maintenance page:
Modify the custom page Open pub/errors/503.phtml and update the content with a user-friendly message. Example:
After modifying the page, clear Magento’s cache to reflect changes:
- php bin/magento setup:static-content:deploy -f
- php bin/magento cache:flush
Disabling Maintenance Mode
- Once maintenance is completed, disable it with:
- php bin/magento maintenance:disable
Check the status to confirm:
- php bin/magento maintenance:status
If disabled, the output will be:
- Maintenance mode is not active.
Troubleshooting Maintenance Mode Issues
1. Site Still in Maintenance Mode After Disabling?
- Check if the var/.maintenance.flag file still exists. If it does, remove it manually:rm var/.maintenance.flag
2. Getting 503 Errors After Maintenance Mode is Disabled?
Try clearing cache and restarting your web server:
- php bin/magento cache:flush
Conclusion
Magento 2 maintenance mode is an essential feature for safely performing upgrades, security patches, extension installations, server maintenance, and other critical updates. By temporarily restricting public access, you can prevent customers from encountering errors or incomplete functionality during maintenance activities.
Additionally, Magento 2 allows you to whitelist specific IP addresses for testing and customize the maintenance page to provide clear communication and maintain a professional brand experience. Following these best practices helps minimize downtime, improve customer trust, and ensure a smooth update process for your online store.
Frequently Asked Questions (FAQ)
1. How do I enable maintenance mode in Magento 2?
You can enable maintenance mode in Magento 2 by running the following command from your Magento root directory:
php bin/magento maintenance:enable
Once enabled, visitors will see a 503 maintenance page while administrators or whitelisted IP addresses can continue accessing the website.
2. How can I allow my IP address during Magento 2 maintenance mode?
Magento 2 allows specific IP addresses to bypass maintenance mode. Use the following command:
php bin/magento maintenance:allow-ips YOUR_IP_ADDRESS
For example:
php bin/magento maintenance:allow-ips 192.168.1.100
This is useful for developers, administrators, and QA teams who need access to the store while maintenance is in progress.
3. Why is my Magento 2 store still showing the maintenance page after disabling maintenance mode?
If the store remains in maintenance mode after running:
php bin/magento maintenance:disable
check whether the maintenance flag file still exists:
rm -f var/.maintenance.flag
Then clear the Magento cache:
php bin/magento cache:flush
If the issue persists, restart your web server and review the Magento logs located in var/log/system.log and var/log/exception.log.
Related Articles
- The Magento Based Website Is Not Working With HTTPS
- How to Resolve the Autoload Error While Installing Magento2 in Ubuntu 18.04 & 20.04
- How to Update Secure and Unsecure URLs Directly in the Magento Database
Talk to our experts
Looking for the right technology solution for your business? Our team of experts can help you with development, cloud, DevOps, design, and a wide range of other technology needs. Get in touch with our team here.