At some point, your website will probably encounter an issue. When issues arise, you would need to troubleshoot your WordPress site. One of the most effective ways to discover the causes of errors is using the debug mode in WordPress.
Although debug mode helps in troubleshooting, it may expose sensitive server information to users if not used properly.
In this guide, we will explain what WordPress debug mode means. Then, we will show you the right way to enable it in WordPress.
Content:
- What is WP Debug Mode?
- How to Enable Debug Mode in WordPress
- Disable Debug Mode After Troubleshooting Your Website
- WP Debug Constants Explained
- Conclusion
What is WordPress Debug Mode?
WordPress is a content management system built and maintained using PHP. This means the core files as well as theme and plugin files are based on PHP.
Like all software, you may run into issues when using WordPress. Fortunately, WordPress has a debugging tool that logs PHP errors and warnings occurring on your website.
The debug mode is used to troubleshoot errors and warnings that occur on WordPress websites. When enabled, it can pinpoint the root cause of the issue you are experiencing on your website.
Once you discover the cause of the error, you can proceed to resolve it or hire a professional to help you fix the issue.
Note that debug mode can expose sensitive data to users if enabled on a live site. However, you can bypass this issue by logging the error messages in a file on your hosting server.
How to Enable Debug Mode in WordPress
Here we will show you two ways you can enable debug mode in WordPress – manually or using a WordPress plugin.
As earlier mentioned, debug mode will display PHP errors on your website’s front end and on the WP admin dashboard. For this reason, we recommend doing this in a staging environment as the error logs may result in a bad user experience and can affect your site performance.
Using a WordPress Plugin
The easiest way to enable debugging is to use a WordPress plugin. One plugin that does the job correctly is the WP Debugging plugin.
This plugin is easy to use. You only need to install and activate it and your site’s debug mode will automatically turn on.
To install this plugin, login to your WordPress dashboard and then go to Plugins >> Add New. On the search box, type in “wp debugging”.
Next, click on the Install Now button next to the plugin name. After the installation completes, the button changes to “Activate”. Click on it to activate the plugin.
The plugin does not need additional configuration to work. It will automatically enable debug mode as long as your wp-config file is writable (i.e. can be edited externally).
To access the plugins page, go to Tools >> WP Debugging.
The plugin automatically adds the following lines of code to your config file.
define( 'WP_DEBUG_DISPLAY', false );define( 'WP_DEBUG_LOG', true );define( 'SCRIPT_DEBUG', true );define( 'SAVEQUERIES', true ); |
We will explain what some of these constants do later in this guide. For now, you can visit your website and replicate the issue by refreshing the error page.
After that, you need to log into your hosting dashboard or access your files using ftp and locate the debug.log file. The file will be stored in the wp-content folder on your web server.
If there are any errors or warnings, they will show up in the file. The information in this log file can be helpful when troubleshooting your website.
After troubleshooting your website and fixing all issues, we recommend uninstalling the plugin to disable debug mode on your website.
Manually Enable Debug Mode in WordPress
The plugin method we explained above works quite well if you have admin access to your WordPress site. But what happens when the error you are troubleshooting is denying you access to the WordPress admin panel?
An example is the white screen of death or blank admin panel errors. You need to enable debugging manually to ascertain the cause of the issue.
There are two ways to manually enable debug mode in WordPress, using cPanel or through an FTP client. We will explain both methods in this guide.
Before making changes to your WordPress core files, we recommend you backup your website. The backup will allow you to restore your site if something goes wrong.
Using cPanel
To start, login to the control panel of your WordPress hosting account, then locate and select the File Manager icon.
On the “File Manager” menu, double-click on the directory containing your WordPress site files. This is usually the public_html folder. Though if your WordPress files are in a different folder, you need to select that folder.
Inside this directory, you will see all your website files. Select the wp-config.php file and then click on Edit. It will open up an online editor to edit the file.
This file contains your WordPress site’s configuration settings. You will find the debug mode settings set to “false” by default.
To enable debug mode, simply change the value from “false” to “true” (without the quotation mark).
If you can’t find the debug mode code, then copy and paste the code below to the config file. That’s just before the line that reads “That’s all, stop editing…”.
define('WP_DEBUG', true ); |
Once you are done, click on the Save Changes button to register your changes.
When you visit your website, it will show any error that occurs before the page was rendered. If the error is preventing you from accessing your site, you will see visual feedback on what is causing the error.
If you want to log the debug messages in a file, then replace the debug line of code with the following code snippet.
// Code to enable debug mode// Log errors to a log file located at /wp-content/debug.log// Disable display of errors on website frontend// Use dev versions of core JS and CSS files. |
The code above will disable error logging on your website and send the errors into an error.log file. Ensure you paste the code just before the line that reads “That’s all, stop editing…”
Enable Debug Mode From FTP
If you do not want to use cPanel, you can also use FTP. For this, you need to access your website files via an FTP client such as FileZilla. We have a detailed guide on how to use FTP for beginners.
After connecting your website to an FTP client, you will see your website files on the right side of FileZilla. You need to navigate into the root directory containing your website files. This is usually the public_html folder.
In this directory, you will see the wp-config.php file. Right click on the file and select View/Edit. After that, choose your preferred text editor.
In the editor, you will see the WP_DEBUG line of code. To enable it, change the value to “true” as seen below.
Similarly, if you want to create a log file to store the error messages, copy and paste the php code below into the config file.
// Code to turn on debug mode// Log errors to a file located at /wp-content/debug.log// Disable display of errors on website frontend// Use dev versions of core JavaScript and CSS files. |
When you save the file, Filezilla will detect the file changes and prompt you to reupload the wp-config file with the latest changes. Tick the option to overwrite the old file.
After making the changes, visit your website to reproduce the error, and then check the wp-content folder for the debug.log file. The file will be populated with errors and warnings occurring on your website.
Before making any changes, always back up your website to prevent data loss. This practice is especially important if you’re dealing with security issues. In the event you need to fix a hacked WordPress site, having a recent backup ensures you can restore your site to a safe state.
Disable Debug Mode After Troubleshooting
Debug mode can be useful when troubleshooting your website. However, you should disable it as soon as you resolve the error.
The reason for that is it displays PHP errors, notices, and warnings on your website pages. These warnings can give attackers access to sensitive information about your WordPress installation.
If you used the plugin method, simply uninstall the plugin from your website and the debug settings will revert back to the defaults.
However, if you manually enabled debugging on your website, you need to remove the code from your config file. You can also simply set the debug value to false.
Understanding the Debug Constants
As we mentioned above, the WP_DEBUG constant is used to turn on debug mode in WordPress. However, this constant will display the error messages on your website pages.
To prevent this, you can add some parameters to control how the debug option works. Here is a list of constants that you can use.
WP_DEBUG_LOG: When set to true, it creates a new log file where every log message is stored. By default, the file is stored at “wp-content/debug.log” on your hosting server. But you can set your preferred storage location. For this, replace the ‘true’ value with the file path. So the code will look like this.
define( 'WP_DEBUG_LOG', 'logs/wp-error.log' ); |
WP_DEBUG_DISPLAY: This constant controls whether the PHP errors are logged on the screen or not. If you are using the debug log file option, then it makes sense to set this value to false.
SCRIPTS_DEBUG: By default, WordPress serves minified versions for core CSS and JS files. This helps to improve the speed of the platform. If you enable “scripts debug”, WordPress will use the original scripts. This can be useful if you made changes to core CSS and JS files on your server.
SAVEQUERIES: This constant is used when you want to troubleshoot your WordPress database. When enabled, it will track the database query being called, the function that triggered it, and how long it took.
If you are using the plugin method we explained above, this option will be automatically enabled. However, you can manually enter the code below into your config file to enable the query monitor option.
define( 'SAVEQUERIES', true ); |
Conclusion
Enabling debug mode can help you easily troubleshoot common WordPress errors. However, it should be a temporary setting. You should disable it after fixing the issue on your website.
In this guide, we explained all you need to know about debug mode in WordPress. We then showed you how to enable debugging in WordPress using plugins and manually editing the wp-config file.
Utilizing WordPress Debug Mode is an effective way to identify and fix issues that may be hindering your site’s performance. By proactively addressing these problems, you not only enhance functionality but also achieve WordPress Speed Optimization, leading to a better user experience and improved search engine rankings.
If you are still having challenges with your website, you may decide to seek professional WP help at this point. One of our WP experts will jump in to fix your issue in no time.
Finally, we explained some additional debug constants that can be helpful when troubleshooting your WordPress site and database. For more WordPress tutorials, do check out our WP College.