# How to Enable WordPress Debug Mode to Troubleshoot Site Errors
A blank white screen. An HTTP 500 Internal Server Error. The WordPress admin dashboard refusing to load. If you manage a self-hosted WordPress site long enough, you will run into all three. The instinct for many beginners is to panic and reinstall everything — wipe the database, delete the files, start over. That is almost always the wrong move.
Most of these failures come down to code conflicts or a plugin that is incompatible with something else on the site. And WordPress ships with a built-in debugging system that can usually pinpoint the exact file and line number causing the problem within a few minutes. This guide walks through how to turn it on, how to read the output, and how to avoid the security mistakes that catch a lot of site owners off guard.
## Step 1: Locate the `wp-config.php` File in Your Root Directory
No matter where your site is hosted — SiteGround, BlueHost, an AWS instance, an Alibaba Cloud VPS, or a local development server — every standard WordPress installation has one core configuration file at its root: `wp-config.php`.
To reach it, connect to your server however you normally do. If you use a hosting control panel or file manager, you can edit the file right in the browser. If you are on shared hosting, an FTP client such as FileZilla works well. Navigate to your website’s root directory, which is typically named `public_html` or `wwwroot`, locate `wp-config.php`, and open it for editing.
If you only see a `wp-config-sample.php` file and no `wp-config.php`, your WordPress installation has not been completed yet. Run the setup wizard first.
## Step 2: Replace the `WP_DEBUG` Constants
Scroll through the file until you find a line that looks like this:
“`php
define( ‘WP_DEBUG’, false );
“`
Many tutorials stop here and tell you to flip `false` to `true`. That technically works, but on a live site — especially a B2B or e-commerce site that real customers are browsing — it is a risky shortcut. A much better approach is to use the full set of three debug constants together:
“`php
define( ‘WP_DEBUG’, true );
define( ‘WP_DEBUG_LOG’, true );
define( ‘WP_DEBUG_DISPLAY’, false );
“`
Replace the original single line with the three lines above, then save the file.
Here is what each constant does:
– **`WP_DEBUG`** — The master switch. Turns on PHP error reporting and WordPress’s internal notices and warnings.
– **`WP_DEBUG_LOG`** — When set to `true`, WordPress writes every error, warning, and notice to a log file instead of (or in addition to) displaying them on the page. The file is created at `wp-content/debug.log`.
– **`WP_DEBUG_DISPLAY`** — When set to `false`, this suppresses error output on the live web page. Visitors see a clean site; you see the errors only in the log file.
Once saved, WordPress’s debugging engine is running silently in the background. It will start capturing PHP errors the next time any page on your site loads.
## Why Log to a File Instead of Displaying Errors?
This is a question of both security and usability, and it is worth understanding before you skip it.
If you only set `define( ‘WP_DEBUG’, true );` and leave display on, every PHP error gets printed directly into your page HTML. That creates two serious problems on a production site:
1. **Loss of customer trust.** Visitors to your site — including potential clients, partners, or shoppers — will see raw PHP error strings mixed into your content. On a business site, that looks unprofessional and actively damages credibility.
2. **Security exposure.** PHP error messages routinely include absolute server file paths, database table prefixes, and sometimes function call traces. That is exactly the kind of information an attacker can use to map your server and find weaknesses.
Logging to a file solves both problems. Errors are captured silently and written to `debug.log`, where only you — someone with file access — can read them. In practice, this approach tends to dramatically cut down the time it takes to isolate a plugin conflict or a failed API integration. For complex workflows like WooCommerce payment gateway debugging, where a checkout might fail five layers deep inside an API request, the log captures the full failure trace that a white screen simply cannot show you.
## Step 3: Read `debug.log` to Find the Culprit
After saving your `wp-config.php` changes, go back to your browser and reload the page that was broken. Then return to your server and navigate into the `wp-content` directory inside your site root. You should now see a file named `debug.log` sitting there.
Download it and open it in any text editor. The most recent errors are at the bottom of the file — that is almost always where you want to look first.
A real-world example of what you might find: the last line in the log reads something like:
“`
PHP Fatal error: Uncaught Error: Call to undefined function wc_get_order() in /public_html/wp-content/plugins/stripe-gateway/includes/class-wc-gateway-stripe.php on line 45
“`
That single line tells you nearly everything you need to know:
– **`Fatal error`** confirms this is a hard failure — the kind that produces a white screen, not a minor warning.
– **`plugins/stripe-gateway/…`** points straight at the Stripe payment gateway plugin as the source.
– **`on line 45`** tells you the exact line of code that failed. In this case, the plugin tried to call WooCommerce’s `wc_get_order()` function before WooCommerce’s core files had finished loading.
With that information, the fix is usually obvious: disable the offending plugin, update it, roll back to a previous version, or contact the plugin developer with the specific error and line number. The guesswork is gone.
## Practical Tips and Pitfalls
**Turn debug mode off when you are done.** Once your site is live and serving real traffic, set `WP_DEBUG` back to `false`. Left running indefinitely, `debug.log` will grow with every page load and every minor notice. Over weeks or months, that file can balloon to hundreds of megabytes, slow down disk reads, and in the worst case fill your server’s storage entirely. Debug mode is a diagnostic tool, not a permanent setting.
**Use the Query Monitor plugin for deeper analysis.** If you want more than raw error logs — for example, seeing which database queries are slowing down a page — install the free **Query Monitor** plugin from the WordPress plugin directory. It adds a panel to the admin toolbar that surfaces API requests, PHP errors, and per-query database timings directly in the browser. It is one of the most useful free tools available for performance tuning a WordPress site.
**Clean up old log files regularly.** During active development, `debug.log` can reach tens of megabytes in a single day. A good habit is to clear or archive its contents weekly so your development environment stays lightweight and the file stays easy to search.
## Summary
WordPress is a transparent content management system. Once you know how to read what it is telling you, debugging a broken plugin, a failed payment integration, or a white-screen error becomes a methodical process rather than a guessing game. The next time your site throws a 500 error or goes blank, do not reinstall — open `wp-config.php`, enable logging, reload the page, and read `debug.log`. The answer is almost always right there at the bottom of the file.
*Note: The steps above apply to standard self-hosted WordPress installations. WordPress.com hosted plans operate differently and may not provide direct file access. Always back up `wp-config.php` before editing it.*
