Magento Maintenance Mode: Enable, Disable, Fix When Stuck

Maintenance mode makes your Magento store show a "503 Service Unavailable" page to visitors while you upgrade, deploy or restore. Magento 2 has no admin switch for it: you turn it on from the command line or with a flag file. Magento 1 uses a flag file too. This guide covers both versions, how to keep your own IP able to browse, and what to do when a store gets stuck in maintenance mode.

Enable and disable maintenance mode in Magento 2

Run these from the Magento root directory, as the user that owns the Magento files (not root):

bin/magento maintenance:enable
bin/magento maintenance:disable
bin/magento maintenance:status

maintenance:status tells you whether the mode is on and lists any allowed IP addresses. The storefront and the admin both show the maintenance page while it is on, unless your IP is on the allowed list.

Let your own IP through

To test the store while visitors still see the maintenance page, allow your public IP. Replace the example address with yours:

bin/magento maintenance:enable --ip=203.0.113.10
bin/magento maintenance:allow-ips 203.0.113.10 203.0.113.11

The first command turns maintenance mode on and exempts one address. The second sets the list of exempt addresses. Check your public IP at a site such as ifconfig.me, not the local address of your laptop.

Enable it without SSH: the flag file

If you cannot run the command line, create the flag file over SFTP.

Magento 2: create an empty file at var/.maintenance.flag. Delete it to go live again. Exempt addresses are stored, comma separated, in var/.maintenance.ip.

Magento 1: create an empty file named maintenance.flag in the web root, next to index.php. Delete it to go live again. The Magento 1 admin has no maintenance switch.

Adobe stopped patching Magento 1 in June 2020. If you still run it, plan the move to Magento 2. We can host the store hardened in the meantime and run the move: see managed Magento hosting.

Change the maintenance page

Visitors see a 503 template from the pub/errors folder in Magento 2 and the errors folder in Magento 1. Copy the default skin to a new folder before you edit it, so a Magento upgrade does not overwrite your change.

Before you turn it on

• Back up the database and the files.
• Rehearse the upgrade or deploy on staging first.
• Pick a quiet hour for your customers, and post a notice ahead of time.
• Keep it short. Maintenance mode returns a 503, which tells search engines the outage is temporary. A long outage can hurt your search visibility.

If the store is stuck in maintenance mode

1. Disable it from the command line: bin/magento maintenance:disable.
2. If that fails, delete the flag file with SFTP or SSH: var/.maintenance.flag in Magento 2, maintenance.flag in the web root in Magento 1.
3. Check why it stayed on. A deploy or setup:upgrade that stopped halfway often leaves it enabled. Read var/log and rerun the step before you go live.
4. Flush the caches: bin/magento cache:flush.
5. Fix permissions. If you cannot delete or create the file, the web server user and the file owner differ. Fix the ownership instead of working around it with root.

Your IP is allowed but you still see the page. Magento compares the address it receives, not the one your browser shows. Behind Cloudflare, Varnish or a load balancer, Magento may see the proxy's address unless the real client IP is passed through.

Maintenance mode is not Magento maintenance

If you searched for ongoing Magento maintenance, meaning patching, monitoring, backups and someone to call when checkout fails, that is a different job from a maintenance switch. It is part of managed Magento hosting, where we run the server and your developer keeps the code.

Frequently Asked Questions

How do I turn off maintenance mode in Magento 2?

Run bin/magento maintenance:disable from the Magento root. If the command fails, delete the file var/.maintenance.flag and flush the cache.

Is there a maintenance mode button in the Magento admin?

No. Magento 2 and Magento 1 both lack an admin switch for it. Use bin/magento maintenance:enable in Magento 2 or create the flag file in Magento 1.

Can I use maintenance mode and still test the store?

Yes. Allow your public IP with bin/magento maintenance:enable --ip=YOUR_IP and you can browse the store while visitors see the 503 page.

Arun BansalFounder, ZenoCloud

Arun founded ZenoCloud, formerly ServerGuy, in 2009 and still runs its operations team.