There's something wrong with your site, but WordPress won't tell you what it is. A page stays blank, a button doesn't work, or you just get a message saying a critical error has occurred. You can enable WordPress debug mode by going to wp-config.php the constants WP_DEBUG and WP_DEBUG_LOG on true to place and WP_DEBUG_DISPLAY on false, so that errors in wp-content/debug.log appear instead of on your visitors' screens. Below, you'll learn how to do this safely, how to read the log file, and why you should turn it off again afterward.
What Debug Mode Does
Debug mode is a setting in WordPress that displays PHP errors, warnings, and deprecated function calls, including the file and line where the problem occurs. On a live site, it’s turned off by default. This is intentional, because an error message can reveal file paths or database information that you don’t want out in the open. If you turn it on, you won’t have to guess which plugin is causing the problem anymore. You can see it right there. That’s why, for me, this is the first step for almost any error without a clear message, from a white screen of death until the report is submitted A critical error has occurred.
Three institutions are collaborating. WP_DEBUG Enable error reporting. WP_DEBUG_LOG determines whether those messages are sent to a log file, and WP_DEBUG_DISPLAY or whether they appear on the page itself. So, the correct combination on a live site is: debug on, logging on, and display off. That way, you get the information, and your visitor simply sees the site—or, in the worst case, the same error as before. If you can still access the dashboard, be sure to also check Tools > Site Diagnosis. Under the "Info" tab, you'll see the PHP version, the memory limit, and whether debugging is enabled—I like to list that information next to the log. For a more comprehensive step-by-step guide on troubleshooting errors—from database connection issues to an offline site—please visit Troubleshooting WordPress Errors.
Here's how to turn on debug mode
To enable debug mode, add three lines to wp-config.php, the configuration file in the root directory of your WordPress installation. A typo in this file will take your site offline, so take your time and save a copy first.
- Open the File Manager in your hosting control panel or connect via SFTP, and navigate to your site's root directory.
- Download
wp-config.phpas a backup copy, and open the file in the editor. - Check to see if there is already a line with
WP_DEBUGstate. Please adjust that, because defining the same constant twice will cause an error. - Place these three lines above the comment line that says you should stop editing
define('WP_DEBUG', true);define('WP_DEBUG_LOG', true);define('WP_DEBUG_DISPLAY', false); - Save the file and repeat the step that went wrong.
From that point on, WordPress writes everything to wp-content/debug.log. The file will only appear when there is actually something to report. If you're working on a test copy, then you may WP_DEBUG_DISPLAY You can count on that true. Then you'll see errors right on the screen as you're building, which saves you the trouble of searching for them. If you're working with SSH, you can do it without the editor. With wp config set WP_DEBUG true --raw WP-CLI will set the value for you, and you'll run that command for the other two as well. If you're not used to working with configuration files, read this first Editing WordPress Code. There, I explain how to make those kinds of changes without breaking your site.
Reading the log file
At debug.log Are you looking for lines with PHP Fatal Error around the time you saw the error, because those are the messages that actually crash a page. Open the file and scroll to the bottom; that's where the most recent lines are. Each line lists a time, the type of message, and the path to the file. You can usually tell the source right away from that path. If it says wp-content/plugins/plugin-name/ if so, then it's that plugin. Does it say wp-content/themes/theme-name/ If it's there, then it's part of your theme.
Don't panic if you see a log full of notifications. A Notice or Deprecated is a signal to the plugin developer that something is outdated, not an immediate error. Many sites have hundreds of them, and the site works just fine. A Warning It's worth noting, but it usually doesn't break the page. You'll find it in debug.log If nothing appears, check the server's error log as well. On our hosting service, PHP writes errors to a file error_log in the directory where the error occurs. There, you can also catch errors that occur before WordPress starts its own logging. If you want to see which requests came in around that time, you can find the access log in cPanel under Raw Access.
Work safely, then turn it off again
Always turn off debug mode after you've finished your diagnosis, because the log file keeps growing and is stored by default in a location that anyone can access. Many people aren't aware of this. Anyone who knows the address /wp-content/debug.log If you type this after your domain, the file can simply be read on many servers, including paths and sometimes data from forms. You have two options. You can have the log written to a different location by setting WP_DEBUG_LOG specifying a path outside your public folder instead of true, or you can block the file with a line in .htaccess. Examples of such rules can be found in The .htaccess File Explained.
When you're ready, press WP_DEBUG back to false or delete the lines, and also delete debug.log. If you want to dig deeper, there are two more switches. SCRIPT_DEBUG loads the unminified WordPress scripts, which is useful for troubleshooting JavaScript issues, and SAVEQUERIES logs every database query. The latter slows down your site, so it belongs on a staging environment. A plugin like Query Monitor makes this information easy to read and helps identify the causes of a slow WordPress site.
What we offer at Surver with our shared hosting plans is everything you need for this. You get File Manager, SSH, and WP-CLI, and those error_logThe server writes the -files itself. On our Managed WordPress Hosting You make the diagnosis yourself. If you want someone else to keep track of updates and step in if things go wrong, check out WordPress maintenance. If the error occurred immediately after an update, the recovery procedure is described in Site Down After an Update.
Frequently Asked Questions
Why isn't a debug.log file being created?
Usually, it says WP_DEBUG_LOG not on true, is WP_DEBUG further on in the file, click it again false set, or the lines appear below the line where you need to stop editing. It's also possible that no error has occurred yet since you turned it on.
Does debug mode slow down my site?
Just a little bit, because every notification is written to disk. On a site with a lot of notifications, you'll definitely notice it. That's why you should only turn it on for diagnostic purposes.
Can I enable debug mode without editing wp-config.php?
Yes, using WP-CLI via SSH or a plugin that sets the constants for you. However, a plugin won't work if you're seeing a white screen, because you won't be able to access the dashboard. On Surver shared hosting, SSH and WP-CLI are available in all plans.
