Text or Call 303.473.4400
Select Page


Magento 2 Custom Maintenance Mode

Magento 2 Custom Maintenance Mode

A free Magento 2 extension by Customer Paradigm.

Put your Magento 2 site into maintenance mode from the admin, and set a custom maintenance mode message.  Perfect for when you need to take the store offline for a few minutes while you update the site, or push new features live.

Instead of having to use FTP or SSH to put your Magento 2 site into maintenance mode, you can use this extension to create a custom maintenance mode message, including using a WYSIWYG editor.

The extension will automatically whitelist your IP address, so that you’re not locked out of the system.  So you’ll still be able to see the site, but anyone else will see the custom maintenance message.

Please note that this extension may not work for sites that have multiple front-end Web servers.  And if your site is in developer mode, the custom message will not display properly (it only will work in “Default” or “Production” modes in Magento 2).

Magento Versions Supported:

  • Magento Community Edition (CE): 2.0, 2.0.1, 2.0.2, 2.0.3, 2.0.4, 2.0.5, 2.0.6, 2.07, 2.1 Beta
  • Magento Enterprise Edition (EE): 2.0, 2.01, 2.0.2, 2.0.3, 2.0.4, 2.0.5, 2.0.6, 2.07

March 3, 2016 Update: We’ve released a new version of the Magento 2 extension, that better supports compilation when your Magento 2 site is in production mode.

This extension is available to be downloaded for free here:

(We ask that you fill out this form so that if we have security or other updates to the extension that we can notify you.)

  • This field is for validation purposes and should be left unchanged.

Need help with Magento? Call 303.473.4400 or visit here to have a real person contact you now >>

Key Features for the Magento 2.0 Custom Maintenance Module:

  • No core re-writes.  This module utilizes XML to point the maintenance page to a custom folder.
  • Custom admin panel created to support features – located at Stores->Maintenance Mode->Global Settings.
  • Ability to enable / disable maintenance mode from the admin.  No longer have to FTP a .maintenance.flag file or create one via command line.  This extension handles the functionality of creating / deleting this file automatically by toggling the admin switch.
  • Ability to create white list of IP addresses directly from the admin.  In addition to handling this through the admin interface, it automatically adds the admin user’s IP address to the white list to maintain admin control while in maintenance mode.
  • Ability to use the WYSIWYG editor to build the maintenance page.  This includes an ability to insert images into the page.
  • For more advanced users, the admin features provides the ability to customize the page using CSS.
  • ACL controls to limit admin user’s access to this feature.


Screenshots / Description for the Magento 2.0 Custom Maintenance Module:


1. Once the Custom Maintenance Module has been installed, you can access it from the Stores tab in the admin area.

How to access the Maintenance Mode module in Magento 2.0 from the admin area.

2. To turn on Maintenance mode on your Magento 2.0 site from the admin, simply select “Enabled” and then hit “Save” on the page:

Your site will now be in maintenance mode:

Toggle Maintenance Mode in Magento 2.0 - from Admin

If you visit the home page of the site and don’t see your custom maintenance message, don’t worry.

This is how it is supposed to work. Your IP address has been whitelisted. (Read more in the next section.)

Simply visit the site from an external IP address (such as your phone on a cellular connection) and take a look to see the maintenance message.

(If we didn’t whitelist your IP address, hitting save would lock you out of your Magento 2.0 Admin Area.)

3. When you visit the Maintenance Mode page, the extension will automatically add your computer’s IP address to the White List IP address list.

This is done so that you can place the site into maintenance mode, but still see the front end of the site and also be able to access the admin area.

How to Whitelist IP addresses so that you can still see the Magento 2.0 Website in the admin area and front end of the site.

If your IP address wasn’t automatically whitelisted, you would be locked out of the Magento admin area as soon as you hit the Save button.

Instead, with your IP address whitelisted, you can see the site, but everyone else (unless their IP address is listed in the White List area) will see the maintenance mode message.

If for some reason you are locked out of the site, you will need to manually delete the .maintenance.flag file via FTP, SSH or via a file manager in your web hosting control panel. This is located in the /var/ directory.

Behind the scenes: when an IP address is added (either by you, or automatically to the system), the system is writing these IP addresses to a small text file on the site.

4. Setting a Custom Maintenance Error Message in Magento 2.0:

By default, the system will pull in the standard Magento 503 error page that reads, “Service Temporarily Unavailable.”

If you’ve been in the eCommerce world for a while, this is not an error message you want to display to your customers. Instead, it’s much better to customize the error message with a bit more of a positive marketing spin. I recommend giving end users an incentive to come back, such as a 10% off coupon code that they can use later.

Here’s the default Maintenance Error Message:

Default 503 error page for Magento 2.0 Maintenance Mode page.

Please note that you can add in HTML text directly into the text box.

You will want to make sure that if you are using images, that you use absolute image source reference links. You might want to have the images for this maintenance page in a different directory (i.e. http://www.domain.com/images/logo.jpg) than you might normally use for your Magento site.

Here’s how to add custom HTML content into the text box to show a better type of a Maintenance message:

Customizing the Magento Maintenance error message page with HTML code.


Note that the image src is a fully-qualified link, using the full https://www.customerparadigm.com/ domain name in front of the image. A relative path will likely not work.

The system uses the <H1> and <P> tags for display purposes.

If you’d like to customize the layout, you can either use inline CSS here, add a stylesheet to the top of the HTML, reference an external CSS stylesheet, or use the Maintenance Mode CSS Styling area to handle CSS:

How to apply custom CSS styling to your maintenance mode page in Magento 2.0

Most of the key Magento functionality, including your main style sheets, are not available when the site is in maintenance mode. Maintenance mode is part of the initial Bootstrap process when Magento 2.0 starts.

5. If you’d rather use the WYSIWYG editor to build this custom page, you’ll need to make sure that you enable static URLs for your media content.

You can enable this by checking the “Use Static URLs for Media Content in WYSIWYG for Catalog” option. You can find this in the admin menu located here: Stores –> Configuration –> General –> Content Management:

6. Once that is selected, the WYSIWYG Editor will now be displayed on the Custom Maintenance page:

Using a WYSIWYG editor for creating a custom maintenance mode page in Magento 2.0


You can then change out the content and see how it will be displayed in the editor:

A better WYSIWYG view of the updated maintenance mode page.


Here’s how the custom maintenance mode message will be displayed in a browser:

Magento 2.0 - Custom Maintenance Mode message, displayed in a browser.

7. Advanced Tip: Meta Refresh – Redirect

If you’d like end users to automatically be redirected to the home page of the site after a brief period of time, you could add in a meta-refresh redirect as an HTML head tag.

In this case, the Maintenance page will be displayed to end users, and then 5 minutes later the site will attempt to redirect them to the home page of the site.

If the site is still in Maintenance mode, then they will see the custom Maintenance mode message again, and their browser will then wait another five minutes before trying to redirect them to the home page of the site.

Add something like this content in the <head> tag area of the page (between the <head> and </head> tags):

<meta http-equiv=”refresh” content=”300;URL=https://www.customerparadigm.com”>

In this case, this script will wait 300 seconds (5 minutes x 60 seconds per minute = 300 seconds total). Math! It’s useful!

Then, the script will redirect the user to the home page of the www.CustomerParadigm.com site.

Note: if you use the exact example above, you will redirect your site visitors to our Website. While we’d love the traffic, this may confuse them, so we’d recommend changing out the URL with the home page of your Magento 2.0 site.

To increase the time, add more seconds. I wouldn’t recommend doing this less than 120 seconds, though, as this will cause more load than necessary on your server.

How to Install the Maintenance Mode Extension on your Magento 2.0 eCommerce site:

You can also download this system via the new Magento Marketplace, in addition to downloading the extension through this site. Here’s how to install this extension for your Magento 2.0 site:

1. Unzip the file Magento-2.0-Custom-Maintenance_Mode.zip into your Magento root folder (the root folder will contain folders such as /app and /pub).
2. From your Magento root folder, change to the folder /bin (i.e. cd /bin).
3. Once in the /bin folder, execute the following command: “php magento module:enable CustomerParadigm_MaintenanceMode” and press enter.
4. Once complete, you should see a message that reads “The following modules have been enabled: CustomerParadigm_MaintenanceMode. If you see this message, the extension has been properly installed.
5. Depending on your cache settings, you may also need to clear cache by running this command from the /bin folder: “php magento cache:clean“.

Now you can navigate from the admin menu to Stores->Maintenance Mode->Adjust Settings for your custom maintenance page setup.



Q: I’ve turned on Maintenance Mode, but I still see the normal Website. Is the extension not working?

A: This is normal. The system has whitelisted your IP address so that you can see the front end of the site and can still make changes in the admin. Try visiting the site from a different computer network, such as your cell phone, or a proxy server. You can try to do an external speed test on the site – this will often render a screenshot of the home page for you.

Q: Why would I ever want to put my site into Maintenance Mode anyway?

A: Perhaps your server is overloaded. Perhaps you are moving from one hosting company to another. Perhaps you need to make some big changes to your site, such as installing a new extension, adding a few new products, putting in a new design theme, or even upgrading the site.

These are all great reasons to put your site into a Maintenance mode.

But most people just put their site into Maintenance mode with the default 503 error message page. And for end customers who visit your site, this absolutely sucks. It makes them think that your site is broken, that their information won’t be safe, and that you don’t know what you’re doing. So, use marketing spin to create a great message letting your end customers know that great things are in store for them at your store, but they have to be patient. Reward them with a discount or coupon code.

Q: I have three frontend Web servers, and when I turn on maintenance mode, only one of them goes into maintenance mode.

A: Depending on how you have your file systems synchronized, the Maintenance mode extension may not work properly with multiple front end web servers.

The reason: Magento needs to write a specific file to the /var/ directory called .maintenance.flag. In most cases with multiple front end web servers, the system will only write to the server that is hosting the admin area of the site.

For example, if you are running your Magento 2.0 site on three AWS EC2 instances with an RDS database, only one of the EC2 instances will likely be placed into maintenance mode through an extension like this one. However, if you’re running multiple front end web servers, you probably have the ability to put those other servers into maintenance mode via FTP or SSH.

Q: I am locked out of my Magento admin after putting my Magento 2.0 site into Maintenance mode through the extension. HELP!

A: This could have happened if you put your site into Maintenance mode, and then closed your laptop and then jumped onto a different wi-fi network. For example, you were at the office, put the site into Maintenance mode, and then went home… only to be locked out of the site.

To fix this and let yourself back in, you’ll need to remove the .maintenance.flag file in your /var/ directory. You can do this via FTP, SSH or via the file manager in a web hosting company’s control panel. (Make sure that you have your settings set to display hidden files.)

Or, you can travel back to your office and see if you can access the site from your network there. If you have a powerful wi-fi network, you might be able to do this from your car in the parking lot, and save the embarrassment of having to call your boss after hours to let you back into the office to unlock your company’s website.

In some rare cases, it’s possible to lock yourself out if you load the maintenance page, select and delete your IP address from the whitelisting box, and then put the site into maintenance mode.

So, have a backup plan. Know your FTP credentials. Or make sure you have a good technical web developer on speed dial (who has these credentials), and likes a nice bottle of Scotch for helping you out in a pinch.

Q: I see part of the Maintenance mode message, but I see other error messages below. Why?

A: Your Magento 2.0 site is probably in “Developer” mode. In Magento 2.0, a site can be in Developer, Default or Production Mode. In Developer mode, the custom Maintenance Mode will not display normally. To change this, simply update the value at the top of your .htaccess file in your root www directory. (Or have a developer do this if you’re nervous about changing files via FTP or SSH.)

Q: What does Whitelisting my IP address mean?

A: When you visit a Magento website that is in maintenance mode, ALL visitors to your site will see the maintenance mode message. EXCEPT if your IP address is listed in a file that allows you to see the site normally.

This allows you to see the site, make changes in the admin area, and do work on the site, but block everyone else.

Q: The images are broken on my Maintenance mode page. Why?

A: Make sure that your HTML img src is using full http://www.domain.com/images/logo.jpg in your HTML source code. Relative image paths will likely not work.

Please note that if you are trying to use images from your normal Magento site, they may not be accessible on the maintenance page. Instead, download these images, and put them in a different directory, outside the normal Magento root folders.

Q: The WYSIWYG Editor is not showing up for me. Help?

A: You must first enable static URLs for Media Content.

You can enable this by checking the “Use Static URLs for Media Content in WYSIWYG for Catalog” option. You can find this in the admin menu located here: Stores –> Configuration –> General –> Content Management.

Q: My boss told me to put the Magento 2.0 site into maintenance mode, but I can’t. Help me!

A: Your boss might not have made you an admin user in the Magento 2.0 store. Only admin users can use the custom Maintenance Mode feature.

If your boss just isn’t a nice person and doesn’t take no for an answer, then you have a few options available to you:

– See if you can guess your boss’s password to the Magento admin area. Try 123456. Or “password” or their favorite sports team. If you’re a good employee, you’ll probably already know his or her birthday, names of kids and pets. See if you can look on Facebook and see if they are still friends with their girlfriend or boyfriend from high school, and see if that works. The downside to this is you might get fired.

– If you have access to your boss’s email, then simply use the password reset option in the Magento admin area to change the password so that you can then log into the site. But cover your tracks and make sure you delete this password reset email quickly so your boss doesn’t know what you did. On Monday, feign ignorance when your boss can’t log into the system, and “recommend” they use the password reset feature. Be extra helpful and tell them to not use 123456 as a password, too. Again, you might get fired for this. But if you have a GREAT boss, they might commend you for your initiative.

– See if you can get direct database access to the Magento 2.0 mySQL system and go into the admin user tables and change your permissions to an admin user. If you’re in a smaller company, this probably won’t get you fired. If you’re in a big corporation with strict dress codes and rules that prevent people from bringing their dogs to the office or having nerf gun fights, this route might also get you fired.

– Learn how to use FTP or SSH to set the maintenance mode directly via the file system. This method shouldn’t get you fired.

Q: How do I uninstall this extension?

A: To uninstall the extension, you’ll want to remove this directory from the site:


You’ll also need to remove the extension from the configuration file in the /app/etc/config.php file as well.

After this, use the Magento command line to reindex and rebuild the site.

Q: I really need to talk to someone on the phone to help me with this.

A: Call us! We’re available on the phone to help – 303.473.4400 or visit here to have a real person contact you now >>.

Please note that this is a FREE extension, so support options are generally limited to paid support from our team.

Q: I found a bug in the Maintenance Mode Extension that’s crashing my site.

A: We’ve tested this on many different systems, and tried to create very clean code that shouldn’t affect your site. But call us! We’re available on the phone to help, Monday-Friday – 303.473.4400 or visit here to have a real person contact you now >>. Or, uninstall the extension with the directions above.


Pin It on Pinterest