If you've found your way to this article, I'm going to assume you've encountered an error on your WordPress website. Or that you're a person who regularly does maintenance and expects to encounter a bug. Either way, I want to remind you that writing code and writing bugs go hand in hand. Even the best developers make mistakes. To make sure you don't go crazy because of these errors, I've written this guide to WordPress debug mode. Debug mode is a very helpful tool to discover and understand bugs in WordPress. 

The first step in debugging your code 

Sit back in your chair, take a few deep breaths and understand that all developers have written buggy code at one time or another. Every time you write buggy code, you learn something – and if you learn something, you'll continue to develop and improve your skills. 

While it can feel like a bug is just there to drive you crazy, luckily that's relatively unlikely 😉 The good thing is: unless you're dealing with the very latest technology, there's a good chance that someone else has already encountered the same bug. 

What is debugging? 

If you're not yet familiar with the term debugging, you can take the word apart to understand it: de - bugging. In computer language, an error in your code is called a bug. So debugging your code means: removing errors from it. Although people like to assume that bugs are caused by their own staff or poorly thought-out software updates, the truth is that many bugs bear your own handwriting – and it's best to come to terms with them early on.

Why PHP debugging seems more complicated than JavaScript debugging

Maybe you're used to debugging in another language, for example JavaScript. A little confusing is that JavaScript is only executed after your website has been rendered – at least this is the standard on the web and the reason why you insert your .js file at the end of the HTML document. This means that your website can still be displayed even if there are JavaScript errors. If you don't notice this or don't check your console log, you may not even know that an error has occurred. 

However, PHP is a server-side language and is used to build your website (although it can do much more than that). So if there's an error in your PHP code, your website may not load and visitors may not see any content. Thus, PHP errors are usually more obvious. 

Debugging in WordPress with WP-Debug 

What is the WordPress debug mode?

If the WP debug mode (sometimes also called wp-debugger or wp-debug) is activated, it shows you errors, hints and warnings reported by the WordPress system. By default, the wp-debugger is disabled. The PHP constant wp_debug is the global variable that indicates the state of the WordPress debug mode via a Boolean, i.e. whether it's switched on or off. 

Why should you use the WordPress debug mode?

Because WordPress uses a few different core components: 

Frontend – HTML / CSS

Backend – PHP / Database

Plugins – PHP applications created by third parties

It can therefore be quite difficult to find out what has caused a problem on your website. The wp-debugger is a tool that allows you to view or log the errors. 

Make a backup before you start debugging! 

There is an old saying that "prevention is better than cure". This means that it is best to prevent a problem from occurring in the first place. For you, that means: Secure your data!

A 30-minute maintenance job can quickly turn into a 5-hour nightmare just because no backup was made before someone messed with the internal files.

Luckily, if you host your website at Raidboxes, the backup is done automatically! Just go to your Dashboard, click on the "Backups" tab and view all your daily backups. 

If you want to make changes and need to create a manual backup, click the "Create manual backup" button and give the backup a name. Tip: Choose a name that makes sense so that you will recognize the backup later. Now you can play around with your website as much as you like! If something goes wrong, just restore your backup. 

Switch on WordPress Debug Mode at Raidboxes

In your Raidboxes Dashboard you can switch on the wp-debugger in the settings of your Box with one click: 

If you click on WordPress Debug Logsafter activating WP Debug Mode, you can see in the Live Log which errors are thrown by your WordPress website. You can access the debug log itself either via the settings in the WP Debug item (see screenshot) or via the BOX overview. You can also access the WP Debug Log files via FTP: Your log files are stored in the /wp-content/ in the file debug.log.

You can find more information about the error analysis of your WordPress website at Raidboxes in our help centre.

In the next section, we explain how to enable WP Debug Mode via wp-config.php when developing locally.

Activate WordPress debug locally 

In your local development, you can enable wp-debug by editing the wp-config.php file in the root of your WordPress folder and adding the following code: 

// Dies aktiviert das Debugging.
define( 'WP_DEBUG', true );

You may also discover that this statement has already been added, but the value is false. If that's the case, simply set it to true. 

// Dies deaktiviert das Debugging.
define( 'WP_DEBUG', false );

At this point, I'd like to emphasize once again how important it is to have a backup. Now is a good time to check this again.  

WordPress debug mode is now active – and now?

Now that the wp-debugger is activated, errors are displayed directly in the browser window (if WP_DEBUG_DISPLAY is set to true) - this is both a curse and a blessing. On the one hand, you can see errors, but on the other hand, all users of your website can see them, which is not ideal. To give you an example, I have added a small unknown function to the footer of the standard WordPress Themes "Twenty Twenty-One". 

Before activating wp-debug: 

After activating wp-debug: 

You probably don't want visitors to your website to see this, do you? The error message not only disturbs the design, it could even reveal sensitive information. For example, before I made some changes to the output, my username was output and with this information, any hacker could launch an attack. 

How to activate the WordPress debug mode and prevent errors from being displayed in your HTML code

Fortunately, there's a solution to this problem in WordPress. Add the following code to your wp-config.php: 

define( 'WP_DEBUG_DISPLAY', false );

This will prevent errors from showing up in your site's HTML code and save your users the nightmare you may have caused. The final piece of the puzzle is how you can check errors without publishing them. Welcome to error logging! 

Activate error logging in WordPress 

In the wp-config.php file, you need to enable error logging from WordPress . This will create a .log file with the logs and details of the errors that occurred on your website. 

define( 'WP_DEBUG_LOG', true );

You'll usually find the log file in the wp-content folder of your WordPress website, unless you have a valid file path for this log as specified below: 

define( 'WP_DEBUG_LOG', '/tmp/wp-errors.log' );

My error log was written to the WordPress root directory, however. So if you don't find your error log in the wp-content folder, you should look elsewhere:  

Reviewing an error log

Error logs give you pretty clear indications of what went wrong. But just because something is clear doesn't mean you understand it, so let's break it down. 

1. Time of the error: [12-Apr-2021 20:32:47 UTC]
2. Type of error: PHP Fatal Error
3. Cause of error: Uncaught Error: Call to undefined function writeMsg() in
4. Where the error occurred: /home/XXXXXXX/DEVELOPMENT/wp/wp-content/themes/twentytwentyone/footer.php:73

In case you're wondering what the error I put in is, I defined an incorrect method called writeMsg() in the footer.php file that causes an error. 

Is the WordPress error log too big?

Error logs can grow over time if they're not controlled. Remember that not only errors, but also warnings and hints are logged. When there are new versions of PHP, certain methods may become obsolete or even plugins may no longer be supported. In that case, more errors will be generated. 

Normally, an error log should only be a few kB in size, but even then it is tedious to search through. In worse cases, the errors are logged in a file that's already several MB in size and contains thousands of lines of text. In addition to being more confusing, this leads to slower reaction times of the log file and can slow down your error search enormously due to waiting times when loading the log. What can you do then? 

Download the file for archiving and then delete it! 

If the WordPress error logs have been activated in wp-config.php and no error.log file can be found, WordPress creates a whole new file and fills it with the current errors.

Conclusion

Debugging code makes development both challenging and rewarding. Because mistakes force you to expand your knowledge, develop a positive attitude and think outside the box. If you have any questions or difficulties with debugging your WordPress website, feel free to leave a comment or contact us in the support chat. Have fun debugging!