Drupal Maintenance Mode Best Practices

In Drupal, maintenance mode is a blunt but useful instrument – one that temporarily takes your site offline for anonymous users while giving site admins room to perform updates or debugging. But beneath that simple toggle lies a system-wide pause: cron jobs stop running, scheduled content doesn't publish, search indexing halts and API/webhook calls may silently fail.

Drupal maintenance mode is a built-in feature that disables front-end access for anonymous (non-authenticated) visitors, displaying a "Site under maintenance" message, while still allowing admin users to log in. It also prevents caching and visitor interactions that could interfere with in-progress updates.

But what most don't realize is that maintenance mode initiates a deeper system-wide pause beyond the front-end. It halts scheduled tasks and background processes critical to many modern Drupal workflows, causing:

• Cron jobs to stop – no scheduled tasks like email digests, content expiration checks or data syncs.
• Scheduled publishing to pause – content scheduled to go live won't be published.
• Search indexing to halt – content won't be indexed for internal search or external services.
• Automated backups to not run – depending on your hosting setup.
• Webhooks and APIs to fail silently – if triggered by unauthenticated traffic or cron, they won't fire.

Drupal maintenance mode is commonly used for:

• Major core or module updates (especially security releases).
• Configuration deployments that may temporarily break layouts or access.
• Theme or layout overhauls that impact front-end rendering.
• Emergency debugging or incident response in production.
• Complex migrations involving content, files or the database.

However, it's important not to rely on maintenance mode as your first line of defense. It's a last-mile tool – not a development workflow. On WebOps platforms like Pantheon, where you have structured Dev, Test, Live environments, you can stage and test changes well before resorting to maintenance mode in production.

Let's explore how to work with maintenance mode effectively when you do need it, common issues you might encounter and modern alternatives that make it largely unnecessary.

Selective access during maintenance

Drupal’s maintenance mode is designed to keep your site safe from anonymous traffic during updates, but in certain real-world scenarios, you often need more flexibility. You might want to let stakeholders preview changes, allow QA testers to validate fixes or enable specific developers to verify a deployment, all without opening up the site to the public.

Fortunately, Drupal enables you to set up granular permission controls that allow selective access even when maintenance mode is enabled. Just navigate to People > Permissions and click on the checkbox under whichever role(s) you want for the Use the site in maintenance mode permission.

Image

Alternatively, you can run the following command:

drush role:perm:add editor 'access site in maintenance mode'

In this example, we assigned the 'access site in maintenance mode' permission to the editor role, but you can assign it to whichever role(s) you want. You can even create a temporary role for review access (e.g., a stakeholder needs to review a homepage change). This ensures access without the full power of administrator permissions.

Additionally, you can override maintenance mode behavior in code for even more granular control in settings.php or via a custom module. And, in a custom event subscriber, you can conditionally allow access based on user agent, IP or custom logic. This is especially useful when working with external APIs or automation scripts that need to hit the site during maintenance.

The cache layer problem

When a Drupal site remains in maintenance mode visually after being toggled off, it's almost never a problem with the setting itself. Instead, it’s often a visibility issue caused by layered caching.

There are three distinct caching layers that must be cleared:

1. Drupal’s internal cache

Drupal caches every major layer of its request/response pipeline to reduce database lookups and render times. This includes routing cache, render cache, page cache, Twig template cache and static cache.

Disabling maintenance mode only updates the configuration state – it doesn’t invalidate cached routes, pages or themes. So Drupal may still serve outdated logic that treats your site as “offline.”

To fix this, run:

drush cr

This command triggers a full cache rebuild, which includes:

• Clearing routing tables.
• Rebuilding menu links and URL routes.
• Flushing all rendered pages and blocks.
• Recompiling Twig templates if necessary.

2. CDN or edge-level cache

Edge caching systems sit between your visitors and your Drupal backend. When a site is in maintenance mode, anonymous users trigger the CDN to cache the offline page. Later, even when maintenance mode is disabled, the CDN continues to serve the cached response, unaware that the backend state has changed.

You may need to manually purge:

• Varnish – clear via the control panel or varnishadm.
• Cloudflare – use the dashboard or API to purge by URL or tag.

If you're using Pantheon, this step is easier. Pantheon uses Fastly to provide a high-performance Global CDN with intelligent purging mechanisms. You can clear the entire edge cache via the Pantheon dashboard or its command line (Terminus). This instantly invalidates the cached responses across all CDN nodes worldwide.

3. Browser cache on the client side

If a user visited your site while it was in maintenance mode, the browser might cache the full page HTML. Even after clearing Drupal and CDN cache, the end user's device may continue to serve the offline page locally.

To tackle this:

• Configure proper cache headers in your settings.php to prevent caching during maintenance mode. Check the sophisticated cache control mechanisms offered by Drupal 11 and Symfony 7 to ensure your manual configurations are optimal.
• Implement resource hints to force browser refresh of critical assets.
• Implement cache warming strategies after maintenance mode to ensure fresh content is properly cached.
• Instruct affected users to clear their browser cache and refresh the page.

Why sites auto-enter maintenance mode and how to fix it

For many Drupal site owners and developers, it can be alarming to see a site suddenly enter maintenance mode – sometimes right after a deployment or without any obvious manual action.

Certain modules and even some core security updates automatically toggle maintenance mode on production sites as a form of "protection." This can leave sites stuck offline if you update production directly without clearing the state afterward.

Here's the key point: maintenance mode is a state value, not a configuration. It's stored in the database only and never exported into YAML files with your other site settings. That means it won't be part of your configuration exports/imports and must be managed separately.

To see if your site is currently in maintenance mode, run:

drush state:get system.maintenance_mode

If the result is 0, the site is live. If the result is 1, the site is in maintenance mode and you’ll need to disable it by running:

drush state:set system.maintenance_mode 0 --input-format=integer

drush cache:rebuild

Or you can use the newer simplified commands:

drush maint:set 0

drush cache:rebuild

A good rule of thumb is to add these commands to your deployment scripts.

That said, the deeper fix is workflow-related. Updating production directly is always risky. The modern best practice is to adopt a Dev, Test, Live workflow with Multidev branches where:

• Each developer gets an isolated environment with their own database and files.
• Configuration and code changes are tested safely before merging to the live site.
• Maintenance mode is controlled deliberately, not triggered accidentally.

This is exactly what Pantheon provides out of the box – structured environments and tooling that make deployments predictable, safe and free of surprise maintenance mode lockouts.

How Pantheon modernizes maintenance mode

Pantheon’s modern WebOps platform makes maintenance mode no longer a necessity in most workflows. In fact, relying on it may indicate that your development and deployment process needs modernization.

Here’s why Pantheon effectively makes maintenance mode more modern:

• WebOps workflow: Pantheon provides every site with three persistent environments, which allows teams to fully develop, deploy and test code, configuration and content changes in isolated environments before they ever touch production:
  • Dev for active development and feature building.
  • Test for integration testing, client review or QA validation.
  • Live, which is the public-facing production site.

Image

• Multidev: For more advanced use cases – like parallel development, stakeholder previews or multiple feature branches – Pantheon offers Multidev environments. These are full Drupal environments (codebase, database and files) spun off from your site, allowing each developer to work in isolation, multiple features to be built in parallel and clients to preview changes in a real site context.

Image

• Terminus CLI: If you do need to use maintenance mode – for example, during a highly sensitive database migration – Pantheon gives you programmatic access through Terminus, its command-line interface. You can enable or disable maintenance mode from your local terminal, script it as part of a Quicksilver hook and integrate it into CI/CD workflows.
• Global CDN: Pantheon’s Fastly-powered Global CDN automatically purges cached content when you deploy, allows full cache clearance from the dashboard or Terminus and ensures content updates (including maintenance mode toggles) reflect immediately.
• Quicksilver and CI/CD integrations: Pantheon’s Quicksilver hooks allow you to script actions before or after deploys, such as automatically disabling maintenance mode after a successful deploy, sending Slack or email alerts, triggering cache clears or downstream integrations. Combined with Git-based workflows and Terminus, this gives you full control over maintenance state as part of automated pipelines, rather than relying on manual toggles.

Use maintenance mode when needed – but work smarter with Pantheon

Drupal’s maintenance mode still serves a purpose. In certain situations – such as critical patching, major database operations or urgent debugging in production – temporarily taking the site offline for anonymous users is justified. But if you're relying on maintenance mode as a default step in your deployment process, it's a sign your workflow hasn’t caught up with modern web operations.

If you host on Pantheon, you gain access to the modern capabilities we mentioned in the previous section so that you don’t need to take your site offline to make updates, test new features or work collaboratively across teams. 

Don’t wait any longer – start using Drupal the modern way with Pantheon!