WordPress Recovery Mode without the email: the one-line fix

White screen. There has been a critical error on this website. Please check your site admin email inbox for instructions. You check the inbox. You check spam. Nothing.

WordPress has a safe mode built for exactly this moment. It is called Recovery Mode, and it normally opens through a link sent by email. When that email never shows up, one line in wp-config.php opens it anyway. The fix comes first, the explanation after.

What Recovery Mode is

Since version 5.2, WordPress catches fatal errors instead of letting them take down the whole site. When a plugin or theme crashes, it records the error, emails the administrator a single-use link, and that link opens Recovery Mode: a safe mode where the offending plugin or theme is paused, so you can log in and deal with it from the dashboard.

Good idea. The email is the weak link.

Why the email never arrives

Three things have to be true at the same time for that email to go out.

“

At exactly the moment you need Recovery Mode, the odds of the email reaching you are slim.

What the constant does

In wp-includes/class-wp-recovery-mode.php, the initialize() method checks for the constant before it looks at cookies or links at all:

if ( defined( 'WP_RECOVERY_MODE_SESSION_ID' ) ) {
    $this->is_active  = true;
    $this->session_id = WP_RECOVERY_MODE_SESSION_ID;
    return;
}

With Recovery Mode active, the fatal error handler skips the email. It records the error, pauses the plugin or theme in the {session_id}_paused_extensions option, and redirects. On the next load WordPress simply skips whatever is paused. Same mechanism as the emailed link, minus the link.

Four things to know first

• It is global. While the constant exists, every visitor sees the site in Recovery Mode. For them that just means the site works instead of showing a white screen, but keep it in place only while you are fixing things.
• Plugins and themes only. Errors from WordPress core, from wp-config.php itself, or from drop-ins like object-cache.php are not paused.
• Multisite. Network-activated plugins cannot be paused.
• The fatal error handler must be on. If wp-config.php contains WP_DISABLE_FATAL_ERROR_HANDLER set to true, none of this works.

And one cleanup case. If you removed the constant before clicking Exit Recovery Mode, the list of paused plugins stays in the database. Clear it by hand:

DELETE FROM wp_options WHERE option_name = 'octopush_paused_extensions';

Replace wp_ with your table prefix and octopush with the session name you used.

If you cannot reach wp-config.php

WP-CLI can generate the link the email would have contained, even with the site down:

wp eval 'echo (new WP_Recovery_Mode_Link_Service(
  new WP_Recovery_Mode_Cookie_Service(),
  new WP_Recovery_Mode_Key_Service()
))->generate_url() . PHP_EOL;' --skip-plugins --skip-themes

Resend the email. Delete the recovery_mode_email_last_sent option that holds the 24-hour lock and reload /wp-login.php. To receive it yourself instead of the client, define RECOVERY_MODE_EMAIL in wp-config.php with your address.

The URL trick. You will also find /wp-login.php?action=enter_recovery_mode recommended around the web. Without the token and key from the email, WordPress ignores it. It is not a way in.

The classic way. Rename the suspect plugin's folder over FTP, plugin-name to plugin-name_off. It works, but you lose the one thing Recovery Mode gives you: the name of the plugin at fault.