When a WordPress site runs into trouble, there isn’t always an error message. You might get a white screen, a simple notice reporting an HTTP 500 error, or just a “critical error” warning, without any further detail. In short, you have symptoms, but not the cause of the problem.
Which is frustrating and unsettling. Because the site is often partially broken or, worse still, completely down and inaccessible.
In a way, it’s like having a fever with no cold symptoms and no pain. You know something is wrong, but you don’t know where or what.
That’s exactly where the WP_DEBUG feature becomes a real ally. It’s the tool that, like a seasoned detective, will guide you (a great deal) through your investigation to find the culprit behind your WordPress site’s problem, and ultimately solve it.
So today I’d like to walk you through a real case from a site I fixed in early September 2026, and show just how much WP_DEBUG can help.
The Case of the WordPress Site with a White Screen and HTTP 500 Error
I recently got a request to fix a fairly straightforward WordPress site. A classic brochure website, no e-commerce, no heavy complex functionality.
On the front end, visitors were seeing a message reporting an HTTP 500 error on a solid white background. As if the domain hadn’t been renewed. As if the problem wasn’t coming from WordPress at all.
So, to find out exactly what was going on, I started by enabling and configuring the tool to display WP_DEBUG.
Those who already use it know how to do this. For everyone else, here’s how to proceed:
Enabling WP_DEBUG: A How-to Guide
WP_DEBUG isn’t really a tool as such. It consists of lines you add to a line that already exists in a cornerstone file of WordPress, namely the wp-config.php file. The wp-config.php file is located at the root of your site in a standard WordPress installation, under the www/ directory. Here’s a screenshot of a wp-config.php file:
Once you’ve located this famous wp-config file, open it and look for this line:
text/* That's all, stop editing! Happy publishing. */
Just below that line, you’ll very likely see the following:
textdefine( 'WP_DEBUG', false );
To enable WP_DEBUG, simply replace false with true. And since we’re troubleshooting a broken WordPress site, we’ll set it to true, but also add a few extra lines like so:
textdefine( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
All the lines must be pasted exactly like this. Don’t add any spaces, quotes, or extra parentheses.
WP_DEBUG: What the Tool’s Lines Actually Mean
You could simply paste these lines and move on. But the idea is to understand what you’re adding.
So here’s what each of the three lines does:
- The first line, WP_DEBUG, when set to “true”, activates the tool used to debug WordPress.
- The second line triggers error logging. Essentially, this will generate and create a file called debug.log on your server, under the /wp-content directory. Opening this file will show you everything that could correspond to errors and bugs on your site — not always with visible symptoms, by the way.
- The third line is used to display the error messages that help you understand why your site is crashing, both on the dashboard and on the front end (what visitors see).
The Case of the 500 Error with a White Screen
I could have done what many do and what’s recommended when troubleshooting, and started renaming WordPress plugin/extension directories. But given the white screen, I sensed the issue wasn’t coming from something standard. Hence the idea of calling in the WP_DEBUG detective.
Before checking what WP_DEBUG was displaying, or even going to the WP_DEBUG log file, I checked which version of WordPress was running on the server.
To check the WordPress version when you don’t have dashboard access because it’s crashed, you can look it up via the version.php file, available in the /wp-includes folder, like this:
Open the file and look as follows:
So our broken WordPress is apparently on version 7.0.4.
Next, I’ll look at what the WP_DEBUG tool says in its logs — namely the text version with dates and times of the errors it detects:
textPHP Fatal error: Uncaught Error: Class "WP_HTML_Tag_Processor" not found
For many, this message won’t help much, but most of the time you’ll get far more precise messages — telling you, for instance, that a given plugin requires a specific version of PHP or isn’t compatible with your current PHP version.
In our case, it’s an error caused by a missing class. And this class is part of a recent version of WordPress : more recent even than version 7.0.4.
If I go to the dashboard login page, another error appears thanks to the debug display feature:
textFatal error: Uncaught Error: Call to undefined function wp_get_toggletip()
Elsewhere, I also see the following:
textNotice: The function WP_Styles::add was called incorrectly...
In short, all of this points to a WordPress update performed remotely — that is, the forced update that triggers the emails you probably receive a few times a year, with subjects like:
Your site has been updated to WordPress 7.1
This can also happen if you let automatic updates run on their own. Note that for plugins and themes, you can disable automatic updates to stay in control of your own updates.
Either way, an incomplete WordPress version can break a site. And figuring that out just from a front-end 500 error is no simple task — even when you’re used to it.
So the WP_DEBUG detective went a long way toward identifying the culprit behind this site’s major crash.
Solving the Incomplete Update Problem
For the record — and the conclusion of the story — in such a case, I download the latest version of WordPress from the official French site. Then I unzip it and upload it to the site using a tool like FileZilla.
And there, no more error message.
Disabling WP_DEBUG
Once you’ve fixed everything on your site, you obviously can’t leave the tool running. So go back into the wp-config.php file and put everything back as it was. Simply replace your three lines with the original one, as follows, then save and close the file:
textdefine( 'WP_DEBUG', false );
That way, the detective can go back to sleep — and hopefully won’t need to help you for a long time. That will simply mean your site isn’t crashing.
A Bit of History
The WP_DEBUG feature has been around in WordPress for a very long time. By contrast, another very useful mode called Recovery Mode is much more recent. “Recovery mode” dates back to February 2019 and WordPress version 5.2. This mode lets you access your site even when, in many cases, it’s broken. As an administrator, you then receive an email with a recovery link.
This recovery mode (in the French version) notably lets you access WordPress for quite a few critical error scenarios.
The two “modes” are different and have been part of WordPress for different lengths of time. But they remain very complementary.
A Bit of WordPress Culture
WP_DEBUG is what’s called a constant in WordPress. The WP_DEBUG mode is used to display PHP-type errors or missing files on the affected WordPress installation. When logging is enabled, the tool — the constant — records errors along with the date and time they occurred, in a file called debug.log.
Here’s what it looks like:
In Short
We sometimes think a site has been hacked or crashed and that fixing it will be a long and complex process. Sometimes that’s true, even in all transparency, it’s far from being the common case. That remains the exception. And besides, tools like WP_DEBUG are precisely there to help with diagnosis. Might as well make the most of them.