How to debug WordPress
This is not a comprehensive step by step to resolving your issue, neither will this cover all eventualities, this is a general guide to be used in the following situations:
- If a website is not working as expected following WordPress and/or plugin updates
- When developing a website
You should review all tasks below before carrying them out - you may choose to carry out the tasks in a different order depending on the issue you are having.
**At no point should any testing or bug fixing happen on the live website, this is a last resort if you are not able to recreate the issue on a dev and/or local build.
Determining the issue
Before you get started, you should check that you can recreate the bug:
- On multiple browsers which have had their cache cleared
- On your local and/or dev builds (where available) ensuring that PHP version is consistent
- You may also (but not essential), import the database to your local and/or dev build if you are not able to recreate the issue
Minor miscellaneous issues
- Checking the
.env
file orwp-config.php
is correct for when working locally so it references the correct database - Issues regarding task runners (related to npm): sometimes it may be quicker to delete the
node_modules
directory and do a fresh install by runningnpm install
, likewise for bower
Determine whether the issue is plugin related
If the bug is occurring consistently, you should:
- Disable all plugins except those that are considered essential i.e. WooCommerce or ACF (Advanced Custom Fields)
- If the issue no longer exists at this point, you should enable one plugin at a time until you are able to recreate the issue
- If you find the troublesome plugin, ensure that this is definitely problematic by disabling/enabling it again
Once you've diagnosed the problematic plugin, you can choose to do the following:
- Look at the plugin settings to see whether there's a workaround
- Source an alternative plugin*
- Write some code so we no longer need the plugin*
- Liaise with the plugin developer and flag the issue
- See whether we need the plugin anymore**
- See whether it is a conflict with another plugin and whether the other plugin is needed**
*These might come at a cost to the client so please check with others first **You may want to discuss this with the wider team to double check whether these plugin(s) are necessary
Determine whether the issue is theme related
Occasionally a theme might to be blame for a particular issue, this might happen be because code might be depreciated or a piece of code is conflicting. Regardless of the cause, the following steps can be taken:
- Install an official WordPress theme
- Enabling this theme and test whether the issue still occurs
- Should the issue disappear, you should review all files in the theme
- The best place to start is in the functions.php file and any includes within that file
Reviewing files
The quickest way we've found to determine problematic code within the theme is to comment out includes and large chunks of code at a time. Between commenting out code, you should test whether the issue still occurs and if it doesn't you know that somewhere within the commented out code is the issue. Narrow down your search by uncommenting code slowly until you find what's causing the issue.
Determine whether the issue is database related
If you have eliminated all steps in the above then your issue is very obscure. It would be good at this point to try a fresh install of WordPress and install the same plugins and theme as the problematic build. If the issue has disappeared, then you know that is this a database issue. You may want to:
- Review all settings to ensure these are correct
- Use a plugin to clean up the database
- Or use the new build to recreate the other website manually (using the WordPress import tool)