What is Magento 2 Maintenance Mode and how do I turn it on and off?


From time-to-time you’ll need to update your modules, backup your store or even upgrade Magento itself. And whilst you’re running these tasks, your store will go into Maintenance Mode. This feature is designed to remove any anomalies or loss of service to your customers whilst you make changes to your store.

When enabled and if you’re in Developer Mode, your site will display this message. And if you’re in Production mode then you’ll see this message instead - Unless you’ve already gone ahead and customised it’s appearance already.

The feature is mostly automated when you carry out specific tasks relating to upgrades and backups. However, you can actually manually activate and deactivate it from the Command Line Interface.

Navigating to the Magento root folder

Right now, I’m logged into my server as my magento user. And I’m going to navigate to my magento root directory by entering

cd /var/www/html/

I can tell this is where my magento files are installed because when I run

ls -la

I can see all those files in the directory that I just navigated to.

Activating Maintenance Mode

Activating Maintenance Mode via the Command Line Interface is very simple and is done so with the following command

bin/magento maintenance:enable

So, now when I refresh my browser I’ll see the Maintenance Mode message.

IP Whitelisting

But now I can’t access the site either! Well luckily Maintenance Mode supports IP whitelisting. There’s a couple of ways I can set this.

Method 1

The first method simply requires adding my IP address to the command I just entered and it would look something like this

bin/magento maintenance:enable --ip= --ip=

As you can see, each IP address I want to enable when I activate Maintenance Mode starts with dash-dash-ip-equals. You can enter multiple addresses this way. So running this command would whitelist 2 IP addresses, and

So, assuming my IP address is when I refresh my browser I can now bypass that message.

Method 2

The second method also allows me do add IP addresses as well as clear the list of exceptions I’ve already created. By entering

bin/magento maintenance:allow-ips

It’s important to note that every time I run this command, it overwrites my previous whitelist. So, now the original IP I enable of has been removed.

I can check both the Status of Maintenance Mode and the list of allowed IP addresses by entering

bin/magento maintenance:status

And if I wanted to, I could clear the entire list of whitelisted IPs by using

bin/magento maintenance:allow-ips --none

In my opinion there is a better way of maintaining this list and I’ll cover that in just a moment.

Deactivating Maintenance Mode

So in order to deactivate Maintenance Mode completely, it’s a simple as entering

bin/magento maintenance:disable

Alternative methods (advanced)

There is another way to Activate, Deactivate and updated IP addresses. Essentially, all of the commands I’ve ran so far have simply been editing a couple of files in the Magento var/ folder. So, if I quickly activate Maintenance Mode I’ll show you what I mean.

Here’s a list of the files in the var/ folder. When I just activated Maintenance Mode I also added a couple IP addresses to the whitelist. In the folder you’ll see an empty file called .maintenance.flag. When you load your site, Magento will see if this file exists in this folder to find out whether it should display the Maintenance Mode message or not. If the file exists then it will display Maintenance Mode and if it does not exist then it won’t.

So, if you needed to then you could just delete the file using the remove file command

rm var/.maintenance.flag

Or create it using the create file command

touch var/.maintenance.flag

It’s not a method you’d use every day, but it’s something I thought was worth noting.

Aside from that trick, I can also view and edit my list of IP address by editing the called .maintenance.ip by entering

nano var/.maintenance.ip

As you can see, this file contains all of the IP addresses that I have whitelist - all separated by a comma. This might be a slightly better method if you’re managing many IP addresses compared to the standard whitelist command.

Let’s say I want to enable a third IP address then I’d just go to the end of the line and type in the IP address and then press Ctrl+X to exist and “Y” and Enter to save.


Magento 2 Modes and how to change between them
Configurable products, problems