WordPress Debug Mode Explained

WordPress Debug Mode ExplainedAt 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 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”.

Add New Plugin's page

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.

WP Debugging's page

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.

File Manager's section in cPanel

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.

Open the public_html folder to enable debug mode

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.

Click on wp-config.php file

This file contains your WordPress site’s configuration settings. You will find the debug mode settings set to “false” by default.

Find the wordpress debug mode settings

To enable debug mode, simply change the value from “false” to “true” (without the quotation mark).

Change wordpress debug mode value to 'true'

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.

Click on save 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
define( 'WP_DEBUG', true );

// Log errors to a log file located at /wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Disable display of errors on website frontend
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Use dev versions of core JS and CSS files.
define( 'SCRIPT_DEBUG', true );

other wordpress debug mode constants

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.

Open public_html folder in FileZilla

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.

Click view/edit on the wp-config.php file

In the editor, you will see the WP_DEBUG line of code. To enable it, change the value to “true” as seen below.

Enable WP_DEBUG in the editor

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
define( 'WP_DEBUG', true );

// Log errors to a file located at /wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Disable display of errors on website frontend
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Use dev versions of core JavaScript and CSS files.
define( 'SCRIPT_DEBUG', true );

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.

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.

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.