You update a plugin, and suddenly your site is a blank white page. Or a cryptic PHP error appears across the top of every page. Or something breaks and you have no idea what caused it. This is where WordPress debug mode becomes invaluable. It surfaces the underlying PHP errors that WordPress normally hides from visitors, giving you the specific information you need to diagnose and fix the problem.
What WP_DEBUG Does
By default, WordPress suppresses PHP errors and warnings. This is appropriate for live websites - you do not want error messages appearing to your visitors. But when something goes wrong, that suppression is working against you. The error is still there; you just cannot see it.
WP_DEBUG is a PHP constant defined in your wp-config.php file that tells WordPress to start paying attention to errors again. When it is set to true, PHP errors, warnings, and notices are captured and can be logged or displayed, depending on additional constants you set.
When to Use Debug Mode
Debug mode is most useful when you encounter:
- White screen of death (WSOD): A blank page with no error message, which almost always means a fatal PHP error occurred
- Plugin or theme conflicts: Unexpected behaviour after installing or updating something
- Site errors after updates: Something broke following a WordPress core, plugin, or PHP version update
- Persistent warnings or notices: Non-fatal issues you want to identify and eliminate
How to Enable Debug Mode Safely
The wp-config.php file lives in the root of your WordPress installation - the directory above public_html/wp-content/. You can edit it via cPanel's File Manager or through an FTP client. Make a backup of the file before editing it.
Look for this line, which is present in most WordPress installations:
define( 'WP_DEBUG', false );
Replace the default debug section with these three constants:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
This configuration is critical: WP_DEBUG and WP_DEBUG_LOG are both true, but WP_DEBUG_DISPLAY is set to false. This means errors are written to a log file but never displayed on screen to visitors. This is the safe configuration for a production site - you can diagnose errors without exposing them publicly.
Reading the Debug Log
With WP_DEBUG_LOG set to true, WordPress writes all errors to a file called debug.log inside the wp-content/ directory. You can access this file through cPanel File Manager by navigating to public_html/wp-content/debug.log, or download it via FTP.
The log file contains timestamped entries showing the type of error, the message, the file it occurred in, and the line number. A typical entry looks like:
[15-Jun-2026 14:23:07 UTC] PHP Fatal error: Uncaught Error: Call to undefined function get_field() in /home/username/public_html/wp-content/themes/mytheme/functions.php on line 87
That single line tells you exactly what broke, which file, and which line. Armed with that information, diagnosing the problem becomes straightforward.
Query Monitor: A Safer Alternative for Production
If you want ongoing visibility into errors, slow database queries, and hook activity without touching wp-config.php, the Query Monitor plugin is an excellent production-safe alternative.
Query Monitor adds a toolbar item visible only to logged-in administrators. It shows PHP errors and warnings in real time, database query times, loaded scripts and styles, and much more - all without logging anything to a file or exposing information to visitors. For developers and power users managing active sites, it is an invaluable tool.
Turning Debug Off After Fixing the Issue
This step is important. Once you have identified and resolved the problem, set WP_DEBUG back to false in wp-config.php and delete the debug.log file.
Leaving WP_DEBUG enabled on a production site has consequences:
- If
WP_DEBUG_DISPLAYis accidentally set totrue, errors show to visitors - The log file can grow very large on a busy site
- Error messages can sometimes expose file paths and code details that reduce your security posture
Debug mode is a diagnostic tool. Use it, fix the problem, and turn it off. The process takes a few minutes and transforms a frustrating blank screen into a solvable problem.
