Magento2 maintenance mode

I use a small Docker image for the development with Magento2. But unfortunately I got a 503 error after every start of the container.

Service Temporarily Unavailable

The server is temporarily unable to service your request due to maintenance downtime or capacity problems. Please try again later.

The problem was really homemade. My setup script tries to install Magento on every start of the container. But that leads me to the point to take a small look at the maintenance mode of Magento2.

Disable maintenance mode

Just for everybody that is searching a fast solution to my little problem. I have just removed the file var/.maintenance.flag and the maintenance mode was disabled.

rm var/.maintenance.flag

A better way is to use the command line tool of Magento.

bin/magento maintenance:disable
Disabled maintenance mode

In general both commands do the same, they remove the empty file var/.maintenance.flag that Magento uses to check if the shop is in maintenance mode. But I would recommend the second version.

Managing the maintenance mode

Just to complete the post I will also list the other commands of the maintenance mode.


The following command returns the status of the maintenance mode.

bin/magento maintenance:status
Status: maintenance mode is active
List of exempt IP-addresses: none

Enable maintenance mode

If we want to disable the maintenance mode, we just need to type the command. This will create the empty file var/.maintenance.flag with a touch.

bin/magento maintenance:enable
Enabled maintenance mode

Allow IPs

If we want to allow some IPs, we can use this command.

bin/magento maintenance:allow-ips
Set exempt IP-addresses:

This will put all IPs from the command seperated by comma into the file var/.maintenance.ip. Only this IPs are allowed to see the shop.

Where is the maintenance mode used?

Here is a small list to get an overview where the maintenance mode of Magento2 is used. In all cases Magento2 will enable maintenance before execution and will disable maintenance after execution. Please keep that in mind when using these commands.

  • The command bin/magento setup:backup
  • The command bin/magento module:uninstall
  • The command bin/magento setup:rollback
  • The command bin/magento theme:uninstall
  • The command bin/magento deploy:mode:set

Development with the maintenance mode

Let us assume we wan't to build our own module that needs to use the maintenance mode. First of all we should import the class MaintenanceMode after our namespace.

use Magento\Framework\App\MaintenanceMode;

After that we have to inject MaintenanceMode in our constructor. Please make sure that the class variable $maintenanceMode exists.

public function __construct(MaintenanceMode $maintenanceMode)
    $this->maintenanceMode = $maintenanceMode;

After that we can use this maintenance service everywhere in our class like this for example.

public function doSomeStuff()
    // do some stuff
Next Previous