Troubleshooting · Guide
How WordPress Recovery Mode Works and How to Use It
Short answer
Recovery Mode is a WordPress feature from version 5.2 that lets you log in after a fatal PHP error. WordPress emails the site administrator a login link, pauses the broken plugin or theme for your session only, and lets you deactivate it, then you click Exit Recovery Mode and check the site.
Key takeaways
- Recovery Mode was introduced in WordPress 5.2 and starts when a fatal PHP error hits a regular page load.
- WordPress emails the site administrator a login link, and the broken plugin or theme is paused for that session only.
- Deactivate the named plugin or theme, then click Exit Recovery Mode in the admin toolbar.
- If no email arrives, rename plugin folders over FTP to find the culprit.
- Recovery Mode cannot pause errors in core files, must-use plugins, or drop-ins.
What is WordPress Recovery Mode?
Recovery Mode is a built-in WordPress feature that lets you log in and fix your site after a fatal PHP error, without using FTP or editing code.
WordPress.org says it was introduced in version 5.2 and can help you regain access when a fatal error occurs, on the Recovery Mode documentation page.
A fatal error is often caused by a plugin, a theme, or custom code, and it stops normal login or site operation, according to the same page.
Instead of a blank page, WordPress enters a safe mode that lets you log in to find and fix the problem. Visitors still see an error message while you work.
What happens when a fatal error hits your site?
WordPress catches the fatal error, shows visitors a short message, and sends the site administrator an email with a link to log in.
WordPress.org says WordPress automatically activates Recovery Mode when it detects a fatal PHP error during a regular page load, but not for errors in CRON or background tasks, on the Recovery Mode documentation page.
Visitors see the message “There has been a critical error on this website.” The page does not show the error details, so file paths and code stay hidden.
At the same time, an email goes to the administrator's email address with details about the problem and a link to log in with recovery mode turned on.
PHP 7 changed how most errors are reported, with most errors now thrown as Error exceptions that become fatal errors when uncaught, according to the PHP migration guide.
How do you use the recovery mode email?
Open the email in your site administrator's inbox, click its login link, and log in to reach your dashboard in Recovery Mode.
WordPress.org says you receive an email in your site administrator's email account with a link to log in and details about the error, on the Recovery Mode documentation page.
After you click the link, you see a notice that says “Recovery Mode Initialized. Please log in to continue.” Log in with your normal admin account.
Faulty plugins or themes are paused just for your admin session, according to the same page. Other visitors still see the error until you deactivate the broken item.
If the email is not in your inbox, check the spam folder. WordPress.org warns the email may be sent directly from your web server and filtered or blocked when the server's mail settings are not fully trusted.
What do you do after you log in?
Look for the notices that name the broken plugin or theme, then deactivate it from Plugins or Appearance > Themes.
WordPress.org says your dashboard loads with error notices pointing to the problematic component, on the Recovery Mode documentation page.
Go to Plugins or Appearance > Themes and deactivate the item the notice names. This is a quick fix, not a repair of the code itself.
If you edited code such as functions.php, correct that code before you move on. The same page lists this as step 3 of the fix.
Do not reactivate the same plugin or theme right away. Find the update or the code change that caused the crash first, or the error will return.
How do you exit Recovery Mode?
Once the broken item is deactivated and the site loads again, click Exit Recovery Mode in the admin toolbar and check the site as a visitor.
WordPress.org says you will usually see the option to exit in the admin toolbar, on the Recovery Mode documentation page.
| Step | What to do | How to confirm it worked |
|---|---|---|
| 1 | Log in through the email link | Dashboard shows the Recovery Mode notice |
| 2 | Deactivate the broken plugin or theme | The notice names it, and it shows as inactive |
| 3 | Click Exit Recovery Mode | The toolbar notice disappears |
| 4 | Visit the site logged out | Pages load without the error message |
If the error comes back after you exit, the real cause is still active. Go back through the email link and check the next notice.
Allow about 15 minutes for a simple plugin conflict. A broken theme file or a code edit can take longer to trace.
What if you never got the email?
Use FTP or your host file manager to rename the suspect plugin or theme folder, which deactivates it without deleting any files.
WordPress.org says you can temporarily deactivate plugins by renaming their folders, for example renaming /wp-content/plugins/hello-dolly to wp-content/plugins/hello-dolly-1, on the Recovery Mode documentation page.
Rename one folder at a time and reload the site after each rename. When the site loads again, the last folder you renamed holds the problem.
If renaming the whole plugins folder brings the site back, rename it back and then rename plugin folders one by one inside it to find the single culprit.
If your host cannot send mail at all, no email will arrive. Ask your host to check outbound mail, and set up proper SMTP after the site is back.
If the error keeps returning after each fix, ask your host to check the server error log as well. WordPress.org says a professional host's support team may be able to help, on the Recovery Mode documentation page.
What if the error is not in a plugin or theme?
Recovery Mode can only pause regular plugins and themes, so errors in core files, must-use plugins, or drop-ins need file access instead.
WordPress.org says a fatal error is often caused by a plugin, theme, or custom code, and its fix steps all point at plugins and themes, on the Recovery Mode documentation page.
If no plugin or theme is named in any notice, the fault may sit in a must-use plugin, a drop-in file, or a core file. Rename those files over FTP one at a time, or restore from a backup.
Our guide on how to fix the critical error on your website covers the same ground step by step, including the cases where email never arrives.
When the site is a multisite network, the single-site recovery flow does not apply in the same way. A network admin should check the network admin screens and the host logs instead.
How do you find the real error?
Read the debug log after the site is back, since it names the file and line where PHP stopped.
WordPress.org says you can still use the debugging methods in the Advanced Administration Handbook, on the Recovery Mode documentation page.
Turn on logging with WP_DEBUG and WP_DEBUG_LOG, which writes errors to wp-content/debug.log, as the debugging handbook explains. Read the last lines of that file first, since the newest fatal error is usually at the end.
Set WP_DEBUG_DISPLAY to false so errors are logged but not shown to visitors. The debugging handbook says this keeps error text out of your pages.
WordPress 5.2, which added both Site Health and this recovery feature, was released on 7 May 2019, according to Kinsta.
What mistakes should you avoid?
The most common mistake is reactivating the broken plugin right after exiting, which brings the error straight back.
- Do not delete the plugin folder before you know it is the cause. Renaming deactivates it without losing its settings.
- Do not edit code on the live site without a backup. The backup handbook says to back up the database first and then the files.
- Do not assume one email fixes everything. Read the debug log to confirm the cause before you call the job done.
- Do not share the recovery link. It logs straight into your admin area, so treat it like a password.
If the screen stays blank instead of showing the error message, read how to fix the white screen of death.
Turn on logging first by setting WP_DEBUG and WP_DEBUG_LOG to true in wp-config.php, so the next error lands in the log file instead of a blank page.
How do you stop the same fatal error from coming back?
Fix the cause, not just the symptom, or the same plugin will crash the site again at the next update.
First, update the broken plugin or theme to its newest version and read its changelog for a fix. If no update exists, look for a maintained replacement that does the same job.
Next, check the PHP version the plugin needs against the version your host runs. WordPress.org recommends PHP 8.3 or greater, and a plugin written for an old PHP version can fail on a newer one, or the reverse.
Finally, make the change on a staging copy first and load the same pages that crashed before. If staging stays up, move the change to the live site with a fresh backup in place.
If you have no recent backup, start with how to back up WordPress before you touch anything on the live site.
Frequently asked questions
Where does the recovery mode email go?
The link goes to your site administrator's email address, and the email may be sent directly from your web server. If it is not in your inbox, check the spam folder and confirm the address under Settings > General. WordPress.org warns the message can be filtered when server mail is not fully trusted.
Does Recovery Mode fix my site for visitors right away?
Yes. The faulty plugin or theme is paused only for your admin session, so visitors keep seeing the error message until you deactivate the broken item. Recovery Mode gives you access, it does not fix the site for everyone by itself.
What if Recovery Mode cannot pause the broken code?
Recovery Mode can only pause regular plugins and themes. Errors in core files, must-use plugins, or drop-in files need file access. Rename suspect folders over FTP, or restore from a backup, and ask your host for help if you cannot find the cause.
How do I deactivate a plugin with FTP?
WordPress.org gives the Hello Dolly example: rename wp-content/plugins/hello-dolly to wp-content/plugins/hello-dolly-1 over FTP. Renaming a plugin folder deactivates that plugin without deleting its files or settings, so you can rename it back later.
How do I know the site is really fixed after I exit Recovery Mode?
After you exit, visit the site in a private browser window while logged out and load several pages, including the page that first showed the error. If every page loads, the fix held. Also read the debug log to confirm no new fatal error appears.
Sources
- Recovery Mode WordPress.org
- Debugging in WordPress WordPress Developer Resources
- Backups WordPress Developer Resources
- Backward incompatible changes PHP.net
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
