Troubleshooting: White Screen & Debug Mode

By the end of this lesson you will handle the scary moments of running a WordPress site: a blank white page, "There has been a critical error", a database error or a site stuck in maintenance. You will turn on debug mode, read an error log and find the guilty plugin in minutes.

Troubleshooting is like a doctor's method. First, do no harm (take a backup). Then find the symptom, test one cause at a time, and change one thing at a time. Guessing and changing five things at once makes it impossible to know what fixed it.

The golden rules

1. Back up first, even when the site is broken. A backup of a broken site is better than none.
2. Ask "what changed?" Most problems start right after an update, a new plugin, a theme change or a hosting change.
3. Change one thing, then test.
4. Read the actual error message. It usually names the file and line.

The critical error and the white screen

When PHP hits a fatal error (an error that stops the code), visitors used to see a blank white page, nicknamed the "white screen of death". Since WordPress 5.2, they see a message instead:

There has been a critical error on this website.

WordPress also tries to email the site's admin address with the subject mentioning a technical issue. The email names the plugin or theme that failed and contains a special recovery mode link.

Step 1: Open the email and click the recovery mode link. You log in to a version of the dashboard where the broken plugin or theme is paused, only for you.

Step 2: Go to Plugins. The faulty plugin is marked with the error details.

Step 3: Deactivate it (or roll back to the previous version), then click Exit Recovery Mode in the toolbar.

Step 4: Visit the site as a normal visitor. It should load again.

If the email never arrives (common when mail is not set up, see Contact & Enquiry Forms), use debug mode.

Turning on debug mode

Open wp-config.php and replace the WP_DEBUG line with these, above the "That's all, stop editing!" line:

<?php
define( 'WP_DEBUG', true );          // report all PHP errors, warnings and notices
define( 'WP_DEBUG_LOG', true );      // save them to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // do not show them to visitors
@ini_set( 'display_errors', 0 );

This combination is safe on a live site for a short time: errors are written to a file instead of being shown on the page. Reload the broken page, then open wp-content/debug.log with the File Manager or SFTP. A typical fatal error looks like this:

[02-Nov-2026 10:15:32 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function bf_get_fee() in /home/bf/public_html/wp-content/plugins/bright-courses/bright-courses.php:42
Stack trace:
#0 /home/bf/public_html/wp-content/plugins/bright-courses/bright-courses.php(57): bf_show_fee()
#1 {main}
  thrown in /home/bf/public_html/wp-content/plugins/bright-courses/bright-courses.php on line 42

Read it like a delivery slip:

• When: the date and time in brackets.
• What: "Call to undefined function bf_get_fee()", so the code calls a function that does not exist (perhaps renamed or in a file that was not uploaded).
• Where: the plugin folder bright-courses, file bright-courses.php, line 42.
• Path: the stack trace shows which code called it (line 57).

Now you know exactly which plugin to fix or deactivate.

When you cannot reach the dashboard

If recovery mode does not work, disable plugins without the dashboard.

Option A: rename the folder. In the File Manager or SFTP, rename wp-content/plugins to plugins-off. WordPress cannot find any plugin, so all are deactivated. If the site loads, rename the folder back, then rename each plugin's own folder one at a time to find the culprit.

Option B: WP-CLI. Tell WP-CLI not to load plugins or themes while it works, so the broken code cannot crash it:

wp --skip-plugins --skip-themes plugin list --status=active --field=name
wp --skip-plugins --skip-themes plugin deactivate bright-courses

bright-courses
contact-form-7
Plugin 'bright-courses' deactivated.
Success: Deactivated 1 of 1 plugins.

If the theme is the problem, switch to a default theme: wp --skip-themes theme activate twentytwentyfive. With no access at all, rename the active theme's folder; WordPress falls back to a default theme if one is installed. This is why you should always keep one default theme installed.

Other common problems

Finding plugin conflicts safely

Sometimes there is no error, but something behaves strangely, such as the menu not opening on phones. The cause is often two plugins, or a plugin and the theme, clashing.

The Health Check & Troubleshooting plugin has a Troubleshooting Mode. It disables all plugins and switches to a default theme only for your logged-in session, while visitors still see the normal site. You then enable plugins one at a time until the problem returns. The last one you enabled is the suspect.

This is like finding which of ten bulbs blows the fuse: switch them all off, then on one at a time.

Getting help effectively

If you need help from your host, a developer or the WordPress.org support forums, include:

• the exact error message or log lines (remove passwords and personal data first)
• what changed just before the problem
• WordPress, PHP and theme versions (from Tools > Site Health > Info, which has a Copy site info button)
• what you already tried

Never post your wp-config.php, passwords or Application Passwords anywhere public.

Common mistakes

• Leaving WP_DEBUG_DISPLAY on on a live site, showing errors to visitors.
• Deleting a plugin folder instead of renaming it, losing its settings and making rollback harder.
• Updating everything at once, so you cannot tell which update broke the site.
• Editing files on the live site without a backup or a staging copy.
• Panicking and reinstalling WordPress. Most problems are one plugin or theme; core is rarely the cause.

Key points

• Back up first, ask what changed, and change one thing at a time.
• "There has been a critical error" means a fatal PHP error; use the recovery mode email to pause the faulty plugin.
• WP_DEBUG, WP_DEBUG_LOG and WP_DEBUG_DISPLAY false write errors to wp-content/debug.log without showing visitors.
• Disable plugins by renaming folders or with wp --skip-plugins plugin deactivate.
• Delete a leftover .maintenance file to end a stuck maintenance message.
• Use Troubleshooting Mode to find conflicts without affecting visitors.

<?php
/**
 * Plugin Name: Broken Demo
 */
add_filter( 'the_content', function ( $content ) {
    return $content . bf_missing_function();
} );

wp --skip-plugins plugin deactivate broken-demo