A WordPress critical error after update is rarely a mystery for long, but the screen itself tells you nothing. Since WordPress 5.2 the core fatal error handler catches the PHP crash, prints a polite white page, and emails the admin a recovery link, deliberately withholding the file and line that would identify the culprit. This tutorial compares the three realistic recovery routes, then implements the one worth keeping: read the fatal from wp-content/debug.log, get back into wp-admin through recovery mode, and roll the offending plugin or theme back with WP-CLI. It finishes with a small mu-plugin that emails you the file and line the moment the next update fails.
You need file or SSH access to the install (SFTP covers the first half), WP-CLI 2.7 or newer for the rollback, and access to the admin email inbox on that site.
The critical error screen is a symptom, not a diagnosis
When PHP hits an uncaught fatal, WordPress runs WP_Fatal_Error_Handler on shutdown. That handler checks whether the error came from a plugin or theme file, pauses the offending extension for the current session, sends the recovery-mode email, and renders the generic template. The message is suppressed on purpose: a raw stack trace on a live site leaks absolute paths, plugin versions and occasionally database credentials.
That design is good for visitors and bad for you. Everything you need is written to a log instead, which is why the first move is never "deactivate plugins one by one" but "turn on the log and read it".
Which of the three recovery routes actually fits your situation?
Route 1: Recovery mode alone: fast, but it only buys you wp-admin
Recovery mode emails a one-time login link that loads the dashboard with the plugin or theme that crashed paused, for your session only. It is the right choice when you have no shell, no SFTP, and one obvious suspect you can deactivate from the Plugins screen. It is the wrong choice when you want to know why something broke, because it never tells you. Visitors keep seeing the error while you are in recovery mode: it is a diagnostic session, not a fix.
Route 2: Debug log plus manual rollback: precise, but slow
Editing wp-config.php over SFTP and reading debug.log gives you the exact file and line. The catch is the fix: without WP-CLI you are downloading the previous plugin ZIP from wordpress.org, deleting the plugin folder, uploading the ZIP, and hoping the settings survive. Workable on a single site, miserable on five.
Route 3: Debug log plus WP-CLI: the one to learn
Diagnosis and repair happen in the same terminal, the rollback is a single command, and the whole sequence is repeatable on the next site. It needs SSH and a working PHP CLI binary, which is the only real cost. The rest of this tutorial implements this route, using recovery mode as the bridge whenever you need the browser.
Step 1: Turn on WP_DEBUG_LOG without leaking errors to visitors
Add these lines to wp-config.php, above the "That's all, stop editing" comment. The debugging handbook page documents every constant here.
// wp-config.php — above the "That's all, stop editing" line. define( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true ); // writes to wp-content/debug.log define( 'WP_DEBUG_DISPLAY', false ); // never print errors into the page @ini_set( 'display_errors', 0 ); WP_DEBUG_LOG does nothing on its own: it only takes effect when WP_DEBUG is also true. And leaving WP_DEBUG_DISPLAY at its default on a live site turns every notice into a visible path disclosure. Setting it to false means the log fills up while visitors see nothing unusual.
Since WordPress 5.1 you can point the log at a path outside the web root, which is strictly better if your host allows it:
define( 'WP_DEBUG_LOG', '/home/example/logs/wp-debug.log' ); Step 2: Read the fatal error line and find the file that caused it
Reload the broken page once, then read the tail of the log. If you have SSH, follow it live while you refresh:
# Follow the log while you reload the broken page tail -f wp-content/debug.log # Or list the 20 most recent fatal lines grep -n "PHP Fatal error" wp-content/debug.log | tail -n 20 A useful line looks like this:
PHP Fatal error: Uncaught Error: Call to undefined function acme_shipping_init() in /var/www/html/wp-content/plugins/acme-shipping/includes/bootstrap.php:3
Read it right to left. The path after in is the file that actually crashed; the number after the final colon is the line. Here the culprit is the acme-shipping plugin, not the theme and not core. If the path points into wp-includes/ or wp-admin/, suspect a half-finished core update rather than a plugin.
The PHP Warning and PHP Notice lines immediately above the fatal usually name the real trigger: a missing option, a removed filter, a class that no longer exists. Reading only the fatal line often sends you to the wrong plugin.
If debug.log stays empty after a reload, the crash is happening before WP_DEBUG is defined (a parse error in an mu-plugin, for example) or the host has disabled error_log. Check the server's own error log at that point: /var/log/php-fpm/error.log, or the equivalent in your control panel.
The fatal error in wp-content/debug.log after a plugin update broke the site (one line per page load) (test site: WordPress 7.1.3, PHP 8.2):
$ grep -n "PHP Fatal error" wp-content/debug.log | tail -n 20 1:[11-Nov-2026 13:38:41 UTC] PHP Fatal error: Uncaught Error: Call to undefined function acme_shipping_init() in /var/www/html/wp-content/plugins/acme-shipping/includes/bootstrap.php:3 11:[11-Nov-2026 13:38:41 UTC] PHP Fatal error: Uncaught Error: Call to undefined function acme_shipping_init() in /var/www/html/wp-content/plugins/acme-shipping/includes/bootstrap.php:3 21:[11-Nov-2026 13:38:41 UTC] PHP Fatal error: Uncaught Error: Call to undefined function acme_shipping_init() in /var/www/html/wp-content/plugins/acme-shipping/includes/bootstrap.php:3 Step 3: Use recovery mode to get back into wp-admin
The recovery email arrives at the admin address with the subject "Your site is experiencing a technical issue". The link inside is valid for 24 hours by default and sets a session cookie, so you can browse the dashboard with plugins paused. The recovery mode documentation explains the email and the session, and the recovery_mode_email_link_ttl filter changes how long the link stays valid if you need a longer window.
Two limits are worth knowing before you rely on it. First, recovery mode only triggers when the fatal is caught by the core handler: a fatal inside an mu-plugin, or inside a file loaded before the handler is registered, will not produce an email. Second, it depends on wp_mail() actually working, which on many shared hosts it does not.
If the email never arrives, you have not lost anything: the WP-CLI route in the next step does the same job without needing mail at all. Do not spend an hour fixing SMTP while the site is down.
Step 4: Roll back the plugin or theme with WP-CLI
Work through this sequence in the WordPress root. The wp plugin command reference lists every flag used below.
# 1. Confirm WP-CLI can bootstrap at all wp core version # 2. If a plugin fatals during bootstrap, skip them entirely wp --skip-plugins --skip-themes plugin list --fields=name,status,version,update_version # 3. Take the suspect out of the equation wp plugin deactivate acme-shipping # 4. Roll back to the last version you know worked wp plugin install acme-shipping --version=2.4.1 --force # 5. Bring it back and re-test wp plugin activate acme-shipping --skip-plugins is the escape hatch when the fatal happens during WP-CLI's own bootstrap and every command dies with the same error. --force is mandatory for a downgrade, without it WP-CLI refuses because the installed version is newer than the requested one. And --version accepts any published tag, which you can find on the plugin's Advanced View page on wordpress.org.
Themes and core follow the same pattern:
# Swap to a default theme, then roll the broken one back wp theme activate twentytwentyfour wp theme install acme-theme --version=1.8.0 --force # Core: reinstall the version you are already on, then check for tampering wp core download --version="$(wp core version)" --force --skip-content wp core verify-checksums wp core verify-checksums is the fastest way to spot a core file that was modified or truncated mid-upload: a common cause of fatals in wp-includes/ after a failed automatic update. If it reports mismatches, reinstall core with wp core download --force rather than patching files by hand. Do not roll core back to an older major version: the update may already have upgraded the database, and older code cannot be trusted to read it.
Step 5: Catch the next fatal error with an mu-plugin that emails you
Core's recovery email tells you that the site broke. It does not tell you where. Drop this file in wp-content/mu-plugins/ (create the directory if it does not exist) and you get the file and line in your inbox within seconds of the crash.
<?php /** * Plugin Name: Fatal Error Notifier * Description: Emails the site admin the file and line of any PHP fatal error. */ add_action( 'shutdown', function () { $error = error_get_last(); $fatal_types = array( E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR, E_USER_ERROR ); if ( ! $error || ! in_array( $error['type'], $fatal_types, true ) ) { return; } $key = 'fatal_notice_' . md5( $error['file'] . $error['line'] . $error['message'] ); if ( get_transient( $key ) ) { return; } set_transient( $key, 1, HOUR_IN_SECONDS ); $body = sprintf( "Fatal error on %s\n\nMessage: %s\nFile: %s\nLine: %d\nRequest: %s", home_url(), $error['message'], $error['file'], $error['line'], isset( $_SERVER['REQUEST_URI'] ) ? esc_url_raw( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : 'n/a' ); // A fatal while plugins load happens before pluggable.php is included, so wp_mail() may not exist yet. if ( ! function_exists( 'wp_mail' ) ) { require_once ABSPATH . WPINC . '/pluggable.php'; } wp_mail( get_option( 'admin_email' ), '[' . wp_specialchars_decode( get_bloginfo( 'name' ), ENT_QUOTES ) . '] PHP fatal error', $body ); } ); Use an mu-plugin rather than a normal one: must-use plugins load before regular plugins, cannot be deactivated by accident from the admin, and are not affected by the very crash you are trying to report. The shutdown hook still fires after a fatal, which is exactly the window this needs. The transient keyed on file, line and message stops a broken page from sending you four hundred identical emails. The function_exists() check matters too: a plugin that crashes while loading does so before WordPress includes pluggable.php, and without the check the notifier dies with a second fatal error instead of emailing you.
If you would rather change the wording of the white screen itself, WordPress also supports a wp-content/php-error.php drop-in that overrides the default template: useful for adding a support address, less useful for diagnosis.
The email the notifier sends, captured on the test site instead of being delivered (test site: WordPress 7.1.3, PHP 8.2):
To: admin@example.test Subject: [Test Site] PHP fatal error Fatal error on http://localhost Message: Uncaught Error: Call to undefined function acme_shipping_init() in /var/www/html/wp-content/plugins/acme-shipping/includes/bootstrap.php:3 Stack trace: #0 /var/www/html/wp-content/plugins/acme-shipping/acme-shipping.php(6): require() #1 /var/www/html/wp-settings.php(597): include_once('/var/www/html/w...') #2 /var/www/html/wp-config.php(106): require_once('/var/www/html/w...') #3 /var/www/html/wp-load.php(50): require_once('/var/www/html/w...') #4 /var/www/html/wp-blog-header.php(13): require_once('/var/www/html/w...') #5 /var/www/html/index.php(17): require('/var/www/html/w...') #6 {main} thrown File: /var/www/html/wp-content/plugins/acme-shipping/includes/bootstrap.php Line: 3 Request: / --- Lock the debug log down before you forget
debug.log sits in wp-content, which is web-accessible on most configurations. A single stack trace exposes absolute paths, plugin versions and sometimes query fragments. Deny it explicitly:
# Apache: deny direct requests for the log printf '<Files "debug.log">\n Require all denied\n</Files>\n' >> wp-content/.htaccess On nginx, add a location = /wp-content/debug.log { deny all; } block to the server config instead: .htaccess is ignored there. Better still, use the absolute-path form of WP_DEBUG_LOG shown in step 1 and keep the file out of the document root entirely.
The log is at its most dangerous immediately after an incident, which is precisely when people leave debugging switched on for a week. Decide where it lives before you need it.
What to do when the fatal is in a theme or in core
A theme fatal almost always follows a theme update or a child-theme template that calls a function the parent removed. Activate a default theme with WP-CLI, confirm the site loads, then roll the theme back and diff the template that appears in the log.
A core fatal is different: core does not spontaneously break, so something changed underneath it. Run wp core verify-checksums first. If it passes, the crash is in a file that core loads but a plugin filters: check the stack trace for the first frame inside wp-content/. If it fails, reinstall core from the same version with wp core download --force; a truncated upload from a dropped FTP connection is the usual explanation.
If the fatal also locks you out of wp-admin and the recovery email never arrives, you can create a new administrator directly in MySQL. And if the white screen turns out to say “Error establishing a database connection” instead, that one has its own checklist: fixing the WordPress database connection error.
The follow-up worth doing this week: add a nightly cron entry that greps the log and mails you a digest, so you learn about fatals from your own inbox rather than from a customer. Something as small as grep -c "PHP Fatal error" /home/example/logs/wp-debug.log piped into mail -s is enough to catch the pattern before the next update takes the site down at 2am.
Originally published on WP Tuts Hub.

