WordPress is a very stable CMS system and, in most cases, works without a hitch. Due to its versatility, however, in certain cases, an issue may pop up. This can happen for several reasons, which is why troubleshooting and debugging are very important. Fortunately, WordPress comes with an essential tool right out of the box that will make the task much easier.
This article takes a look at the WordPress debugging tool before looking at the most common issues that many WordPress administrators and website owners may encounter. We’ll then look at causes and fixes to help you get back up and running in no time at all.
What is debugging?
As the name implies, debugging is a process in which bugs are identified and removed from software code. Most, if not all, software developers will find themselves debugging code – a routine practice when running code.
However, even if the code passes Quality Assurance checks, new bugs may surface after the software has been installed.
This can happen for a variety of reasons, including software being installed in an environment that the developer did not test. It is impossible for software developers and testers to test their code in all possible environments – no software would ever be released. We will delve into more detail about this later on in this article.
In such cases, website administrators and owners may need to do a bit of debugging to help the developers identify the problem. While this may sound like something that is too technical, in reality, it is quite easy. Don’t sweat it; this article will show you how.
What is a bug?
A bug is an unexpected behavior in the software. This unexpected behavior can manifest itself in various ways, including errors, exceptions, warnings, and so forth. It may also cause a function and feature not to work as expected.
When this happens, we need to debug the software, in this case, WordPress. Fortunately, WordPress comes with a debugging tool straight out of the box called WP_DEBUG.
WordPress debugging – WP_DEBUG and WP_DEBUG_LOG
WP_DEBUG is a WordPress debugging tool that comes built-in. Once enabled, it displays all errors, warnings, and notices generated by PHP code – the underlying technology that powers WordPress.
WP_DEBUG_LOG, on the other hand, saves these errors, warnings, and notifications to a log file – making it easier to share with a 3rd party. While this is very different from a WordPress activity log, it logs all of the actions the software does, helping developers identify which elements of the code are acting up.
How to use WP_DEBUG
WP_Debug is fairly easy and straightforward to use. It does require you to have SFTP or SSH access to your WordPress file system directory, so you may want to speak to your hosting provider if you’re not sure whether you have this or not.
Now, the setting is located in a text file, so we’ll need to use a text editor to switch it on. The good news is that this is done from the wp-config.php file, which is located in the root directory of your WordPress installation – making it super easy to find.
The setting you’re looking for is called WP_DEBUG, and this needs to be set to true, as shown below:
// Enable WP_DEBUG mode
define( ‘WP_DEBUG’, true );
To enable logging, you’ll need to enable the WP_DEBUG_LOG option as follows:
// Enable Debug logging to the /wp-content/debug.log file
define( ‘WP_DEBUG_LOG’, true );
If the WP_DEBUG_LOG option is not available, you can simply copy and paste the command into your wp-config.php file.
To stop errors from showing on your WordPress site front end, you can set the WP_DEBUG_DISPLAY option to false as follows;
define( ‘WP_DEBUG_DISPLAY’, false );
Important note: WP_DEBUG should be enabled on your testing or staging environment and not on your live website.
If you are troubleshooting a particular issue, try to replicate the issue while the WP_DEBUG/WP_DEBUG_LOG option is enabled – depending on which options you enabled. Doing so will cause the error, which in turn will cause the debugging tool to write to the log file.
Common WordPress issues
As we mentioned earlier, WordPress is a very stable CMS. Many developers put in countless hours in each release, and many people manage to run it without a hitch. The same goes for themes and plugins from reputable developers. However, issues and conflicts can arise due to environmental variations. This is true for software that is WordPress related, as it is true for any other software. As such, issues may arise from time to time.
A WordPress issue, whether it’s directly related to WordPress or a theme or plugin, does not necessarily mean there is something wrong with the software. More often than not, it is a configuration issue. Either way, WP_Debug can probably help you uncover what is going on.
White screen of Death
Symptom
The White Screen of Death, also known by its acronym WSOD, manifests in your WordPress website, showing a completely blank white screen.
Cause
While many factors can contribute to a WSOD, a common culprit is compatibility issues with plugins and themes. If you have recently installed or updated a plugin, manually disabling the plugin or theme should be your first port of call.
Fix
The debug log file can give you better insight into which plugin and which line of code is causing the issue. If you do determine that it’s a plugin or theme that is the culprit, you might want to get in touch with the developer for a fix. If the issue lies elsewhere, the log file will give you better insight into what is causing the problem.
Database connection issues
Symptom
WordPress database connection issues can happen for a variety of reasons and manifest themselves in different ways. One of the more common symptoms is seeing an ‘Error establishing a database connection’ message on your website.
Cause
WordPress relies on MySQL to store and read data such as settings and posts. Without a connection to the WordPress database, the website will not be able to function. A database connection error can happen for a number of reasons, including connectivity or credentials issues.
Fix
Make sure that the MySQL server is up and running and that WordPress can connect to it. Remember to check firewall rules and the config file, especially if you have made changes or it’s a first-time install. Next, make sure that the WordPress database user has sufficient rights to the required tables and can run database queries.
Memory limit/exhausted
Symptom
When the memory limit is reached, you will see a fatal error that allowed memory has been exhausted.
Cause
The memory limit error is a PHP error that can affect WordPress. PHP, the underlying technology that powers WordPress, uses memory to run applications, including WordPress. The memory limit acts like a hard RAM limit to avoid WordPress consuming too much memory and taking the server down. The default limit is 128MB; however, your hosting provider may set a different limit.
Fix
Before looking to increase your memory limit, make sure nothing is consuming more memory than it should. If your WordPress has simply grown too large for the current memory limit, you may want to increase it. If you’re on a hosting plan, speak with your provider – in most cases, you will need to upgrade your plan.
Parse Error: Syntax Error
Symptom
A Parse Error: Syntax Error is displayed when executing an action on your WordPress website.
Cause
A Parse Error: Syntax Error happens when WordPress tries to execute code but finds a syntax error preventing it from doing so. Generally, this can happen for one of two reasons: either there is code missing, or you are using the incorrect version of PHP.
Fix
Make sure you are running the latest version of PHP. Not only is this an easy fix, but will help you ensure you’re running the latest version, which may include bug fixes. If the error persists, the error itself will tell you which component is having issues. This can help you identify whether its a plugin or theme (in which case you should contact the developer) or WordPress (in which case you should re-upload the WordPress core files.
Maximum execution time exceeded
Symptom
A Fatal error: Maximum execution time exceeded is displayed when executing an action such as updating a plugin.
Cause
A maximum execution time exceeded error can happen if the execution time of a particular action takes more than the allocated time. This time limit is set in place to avoid any one action hogging all CPU time, which may bring down your website.
Fix
To troubleshoot this issue, first, identify which action has caused it. Look at the last thing you did on your website and if you have a WordPress activity log, refer to it. Next, check cron jobs using a plugin such as WP Crontrol and scheduled actions to see if there is anything that is stuck. Enable WP_DEBUG and try the action again. Next, check the error log, and if it’s a plugin or theme, contact the developer. Another option is to increase the execution time.
Internal server error
Symptom
An internal server error, also known as Error 500, displays an Internal Server Error message instead of your WordPress website.
Cause
Internal server errors are not specific to WordPress. It is an HTTP error code that the web server returns when it encounters a problem that it has no code for. This catch-all error can make it difficult to troubleshoot since no other information is provided.
Fix
Fixing a 500 error can involve some trial and error troubleshooting. You may want to start by deactivating all your WordPress plugins and themes, especially if you have recently installed or updated anything. Next, try re-uploading the WordPress core files using an FTP client. Other common fixes include checking your HTACCESS file and increasing the PHP memory limit, which we covered above.
Failed update
Symptom
A failed update error is displayed following a plugin update. A failed auto-upgrade may also be displayed if you have auto updates enabled.
Cause
Updates are one of the most important aspects of good WordPress governance. They provide fixes and can add new functionality. An update may fail to execute for various reasons, including a dropped internet connection, plugins not playing nice with each other, and WordPress file permissions.
Fix
A failed update is unlikely to bring your website down, so trying again is worth a shot in case there was an issue with your connection. Next, check the REST API from the Site Health menu and ensure it’s running. If this does not fix the issue, check the error log for more information.
Maintenance mode
Symptom
WordPress gets stuck in maintenance mode following an update that did not complete.
Cause
Whenever WordPress updates its files, plugins, or themes, it enters into maintenance mode. Doing so allows the application to take files ‘offline’ and update them. During this process, WordPress creates a .maintenance file, which it stores in the root directory. If, for one reason or another, an update breaks, WordPress can get stuck in this maintenance mode.
Fix
To take WordPress out of maintenance mode, log in via FTP or SSH and delete the .maintenance file. You may also need to delete your cache for the website to return back to normal. WP_DEBUG can help you troubleshoot the issue however it is recommended you try this on a staging or testing environment to avoid taking your website down.
My error is not listed above
WordPress environments can be wildly different from each other, and obscure errors can happen from time to time. In such cases, enabling WordPress debug mode is one of the best steps you can take.
While this may sound intimidating, it can help you better understand how WordPress works, and thus become better at it. Remember that having a WordPress testing or staging environment can be of great help. Such an environment is of great help when it comes to troubleshooting issues without risking your live website.
Troubleshooting WordPress
WordPress relies on a number of technologies working together to ensure your website runs. While we covered MySQL and PHP quite a bit, other technologies such as HTML, CSS, and Javascript are crucial to how your website is displayed and functions.
As long as you choose reputable developers, you should be fine, but many times, other factors can contribute to WordPress errors. This is where WordPress debug can prove to be your friend. Speaking of plugin and theme developers, it helps to ensure they offer support so that you can rest easier knowing someone is there to help you should something break.
Troubleshooting is a good skill to have and can help you in countless ways. Not only will you be able to minimize downtime, but it will also come in handy when carrying out a WordPress security exercise for a more secure and safer website.
