The same questions come up time and time again online about how to debug WordPress problems. The challenge with WordPress and the web servers they live on is that there are an awful lot of moving parts, of which one or more of these moving parts can be the root cause of the problem. Unfortunately there is no handy traffic light system which says what is working well and what is causing problems as problems can be intermittent, appear random or only occur under specific circumstances. This being said, there is always a logical way to debug WordPress problems to identify what the root cause of the problem actually is.
Identify What is Actually Happening and When
This is extremely important as this will help you to understand where the problem actually lies. Is what you are experiencing really a WordPress problem or something web hosting related or something email related or something else completely?
Check your Server Raw Access Logs
See what is happening on your web server when you are experiencing the issues. This will help to identify if there are any other external items that could be the potential cause of the issues or if this is indeed an isolated incident.
Check your Server Error Logs
Has anything been resulting in a recorded error on your web server that can help you identify the problem that is happening? Have a good rummage around here to see if you can spot anything and tie this back to the times and dates when the problems are occurring.
Check your Server Monitoring Software
Tools such as Munin and New Relic are invaluable when debugging issues, they can help you identify what is currently happening on your web server. This enables you to see if the problem is indeed WordPress related or an issue that is being caused elsewhere.
Check your Server Firewall
Make sure your IP address isn’t being blocked for some reason. This can sometimes be triggered when you have entered an incorrect password on multiple occasions.
Check your Cloud Based Firewall
As above.
Check your WordPress Firewall
If you have a WordPress level firewall installed, then it is possible that your IP address / user account is being blocked here too. You’ll likely need to check via phpMyAdmin to view this data to see if you can find your IP address in the database for locked users or accounts. Depending on the plugin you are using for this, this data could be anywhere. Check the documents for the plugin you are using to figure out where this information could be. If your IP address is being blocked, it’s usually safe to delete this row and you should regain access. Again, make sure you know what you are doing before you go deleting things though as you may delete a whole host of incorrect things depending on how everything has been set up.
Check if the Problem is Just You
http://isup.me will tell you if your website is up or if it is just you experiencing the problem.
Check in Another Web Browser
Often issues can be browser specific, so check on a different web browser that you have installed.
Check on Another IP Address
Use your mobile phone, with WiFi turned off, to access the website. Is the issue still being caused now?
Check Google Analytics
Is there anything happening at the time when the issues are occurring? This could help you narrow down where the issue lies, for example if you suddenly receive a large spike in traffic which would show on the Real Time reports or on the hourly reports which could show out of the ordinary behaviour on the website.
Check Google Chrome Developer Tools
If the problem is occurring when you are either viewing a specific page or when you are logged in as a user or administrator, open the Google Chrome Developer Tools to see if any issues are being flagged in the console window. If there are any error being flagged here, this should give you an idea of where the problem may be coming from.
Compose Yourself
So far you have been gathering data about what is happening so you can make an informed decision about if you are certain the problem actually lies with WordPress or if it is somewhere else. Assuming you have identified that the problem is indeed WordPress related then continue reading.
Enable WP_Debug
Turn on wp_debug by adding the following line of code to your wp-config.php file;
define( 'WP_DEBUG', true );
Once turned on, this will flag any errors that are being caused by the themes, plugins or PHP files which need addressing. When you turn this setting on, both you and everyone using your website will be able to see the errors. So if you must do this on a live website, do it quickly and turn if off again by setting the value to false.
define( 'WP_DEBUG', false );
On poorly built WordPress websites with plugins purchased from theme market places and other less salubrious sources, this will flag up a whole host of errors. Take note of where these errors are being caused as this will help you to identify where the problem lies and ultimately what you need to do about resolving the issue.
While the WP_Debug option is great, it doesn’t do everything for you. Particularly on custom built systems with lots of custom code and functionality, you need something extra. This is the WordPress Debug Log. Firstly, add the following code to your functions.php file;
if (!function_exists('write_log')) {
function write_log ( $log ) {
if ( true === WP_DEBUG ) {
if ( is_array( $log ) || is_object( $log ) ) {
error_log( print_r( $log, true ) );
} else {
error_log( $log );
}
}
}
}
Then where ever in your code you feel that a problem lies, add the following code to check that this part of the code is actually being called;
write_log('THIS IS THE START OF MY CUSTOM DEBUG');
You’ll also need to make sure that you have the following settings turned on in your wp-config.php file;
define( 'WP_DEBUG', true ); define( 'WP_DEBUG_DISPLAY', false ); define( 'WP_DEBUG_LOG', true );
Then when you start running through your system to check which bits are and aren’t working, you can view the data that is output into the debug.log file which is added to your Document Root for your WordPress installation.
Backup Your Setup
A full backup including database and files. So you can restore the site to it’s current broken, but functional, state if the following debugging ends up breaking things even more. This can happen when WordPress websites haven’t been built particularly well, so make sure you have a full backup. Even better, use a backup plugin which allows you to easily restore everything should you need to. It is a lot easier to restore backups when part of the task is automated.
Update Everything
WordPress Core, Themes and Plugins. Make sure absolutely everything is running the latest versions. Often problems are caused by outdated plugins which are either using deprecated PHP functions or making calls to 3rd party systems which have been updated since they were installed, or even conflicts between other Plugins, Themes or WordPress core that needs resolving. When you have updated everything, at least you know that everything should in theory be working correctly, assuming you are using well respected Themes and Plugins for WordPress and not poorly developed ones.
Disable All Plugins and Themes
This one is the one that on-one ever wants to do, particularly when debugging issues that are only happening on a live website and not on a development server. Unfortunately this is a required step in the process as this will help to identify what is causing the problem.
Firstly switch your Theme back to the latest version of the core WordPress theme such as 2016 and soon to be 2017. These themes have been built as near perfect examples of how Themes should be build, meaning that there are no issues contained within these themes which could be causing the issue. If the issue disappears when you do this, the problem lies with your theme. Contact the theme author to get it resolved so they can push an update out. It is important to note that on occasions, if your website has been built or customised incorrectly then it is possible that any custom CSS (for example if you have stored this in the JetPack plugin Edit CSS area) or other customisations you have made can actually disappear completely, which if this is a large website, then it’s going to take either yourself a good amount of time to resolve, or it’s going to cost you a lot of money to resolve paying someone to re-implement the different aspects properly.
If this doesn’t solve the problem, next, disable all plugins on your website. See if this solves the problem. If so, then it is one of the plugins you’re using which is causing the problem. Systematically re-activate the plugins you are using and check to see when the problem starts to happen again. As mentioned previously, some plugins will delete and customisations when they are deactivated which is annoying and causes more problems to resolve which can often take some time to re-implement some of the customisations. Good plugins don’t do this, bad plugins often do.
Check Server PHP Settings
As part of the process outlined above, on occasions the error lies with the web server, specifically the php.ini settings and configurations. There are various settings which are often causing the problems which include;
- Max_execution_time
- Memory_limit
- Upload_max_filesize
- Post_max_size
Check your WordPress PHP Memory Limit
In addition to the server settings, it is also possible to configure memory limits within WordPress itself. Check within the wp-config.php file to see if any arbitrary memory limits have been added which could be causing scripts to time out and produce errors. The line will look like the example below, likely with a different number included;
define(‘WP_MEMORY_LIMIT’, ‘64M’)
WordPress Debugging Plugins
There are also a few handy WordPress debugging plugins which can provide additional information including WordPress Query Monitor and WordPress P3 Plugin Performance Profiler. When you install these there are various debugging tools included which can help to identify where the root cause of the problem lies.
Check your .htaccess File
Sometimes this can become corrupted, either by someone who has access to the site messing around without knowing what they are doing, or, a plugin may have altered the file which is then causing problems.
Check your Database is Correct
You will at some point when working with WordPress come across the “Error establishing database connection” error which can be caused by multiple things. One thing is clear though, it’s an error connecting with the database.
Firstly, check your database credentials within the wp-config.php file to make sure they are correct.
Secondly, make sure that the MySQL daemon is running on your web server. Sometimes this can get a bit tangled in a knot and need a restart.
Thirdly, sometimes your WordPress database gets corrupted and needs to be fixed. To fix this, when you visit yourwebsite.com/wp-admin, you will see a message that your database needs to be repaired. Sometimes, you can go ahead and implement this straight away. Other times, you need to add the following code to your wp-config.php file;
define('WP_ALLOW_REPAIR', true);
Then visit yoursite.com/wp-admin/maint/repair.php to start the repair process. Be sure to remove this line of code once you have completed the process to prevent others from accessing the URL.
Should none of this work, speak with your web hosting company. On occasions, the maximum size of the database may have been reached or there is something gone really wrong with your database that WordPress cannot restore. All kinds of crazy things can happen and they will be able to identify the root cause of the issue.
Check File Permissions
If your issue appears to be related to file permissions, i.e. you cannot upload a plugin maybe or you’re having trouble uploading an image for example. Then check the file permissions on your web server to make sure that they are set correctly. And make sure to check the owner of the files too. For example, if you have restored a backup via SSH using a root user account, then the files you copy to a cPanel account for example will belong to that user and not the cPanel account user, meaning that you technically don’t have permission to do anything with them when you are trying to do so via your WordPress interface. This is rare, but worth checking.
Check that Maintenance Mode Hasn’t Got Stuck
If you have been updating WordPress core, Plugins or Themes and your maintenance mode has got stuck, it is likely that it has timed out and not been able to complete. What this means is that you’ll first need to identify why this has happened in the first place, check your error logs for details.
To get you back up and running though, login to your server via FTP, make sure hidden files . [dot] files are showing and you’ll likely see a .maintainence file. This is the file that WordPress adds when it is doing maintenance, which is then deleted at the end of the process. So if the process timed out, it didn’t complete and the file is still there which causes the message to appear for everyone. Delete this file and you should be back up an running.
Re-Save your Permalinks
Bizarre things can happen related to permalinks which cause strange issues around the site such as 404 errors showing and more. Even when they look correct when you view them in the settings page, just re-save them. Often this can fix random errors which you haven’t been able to identify yet.
Check your PHP Version
WordPress websites are hosted on a variety of PHP versions. What this means is that with newer and older versions of PHP, certain functions are not available that your Plugins or Themes may be trying to use. There is no easy way of debugging issues like this and as such, this is a last record for identifying issues, so rebuild you web server with different versions of PHP to see if this solves the issue. One recently I came across related to email not being sent via a plugin due to a specific version of PHP that was being used. The lower version of PHP did work but broke something else, the newest version didn’t work but the other thing was fixed, the middle version broke something, etc. In the end the solution was to upgrade to a newer version and fix on of the bugs that was being caused elsewhere. No simple solution to these types of problems.
Check WordPress User Permissions
Sometimes issues can relate to what permissions a specific WordPress user has. Set up the Members WordPress plugin to see if the issue relates to a specific user group as to why they can or cannot do something.
Monitor What WordPress Users are Doing
When multiple administrators have access to the website, all with varying levels of skill, it is impossible to know what people are changing and when. Install a plugin such as Stream which can log all of this information which can come in handy for debugging issues next time around.
Summary
Following the above process systematically can identify the root cause of the majority of WordPress problems. Often identifying is a completely different thing than fixing the problem. Often during this process you will realise that your website has been built fairly poorly and requires a significant overhaul. Should you require any support debugging your WordPress problems, get in touch and we’ll happily help.
Michael Cropper