Tricks for Debugging Common WordPress Errors
For me, the trick to debug and resolve WordPress website issues is to act a bit like a detective. You look for clues as to why a site isn’t working.
Some WordPress problems have obvious solutions. For instance, an error message in WordPress may mention a particular plugin, so you know the identity of the offender.
How to debug WordPress plugin errors
When a plugin is the culprit, there’s a surefire way to tell.
If you have access to your web host’s panel and you know where to find the plugins folder in wp-content, look for the folder for the plugin you suspect. When you find it, rename the folder to something else (nameofplugin-old, for instance) and see if that resolves things. If the error message disappears after you change the name of the plugin folder, then you need to find out why the plugin is causing errors.
One of the best ways to learn about issues with a free WordPress plugin is to visit the support forum for that plugin. Usually when a plugin is causing issues, you’ll see posts about that in the support forum for the plugin and solutions may be posted there.
Find WordPress support to help you debug plugin issues
To find the support forum, in the WordPress Dashboard look for Plugins. You’ll see the list of what you’ve installed and information about the plugin’s support forum should be under the Details tab. Or visit this page to search for a support forum under WordPress.org.
Sometimes you’ll need to deactivate the plugin or roll it back to the previous version and wait for the next plugin update. If the plugin is causing too many issues with other plugins or your site or it’s no longer supported, then it’s probably best to deactivate and delete it.
In the case of a premium (paid) plugin, the best route is to get in touch with support for that plugin. Most premium plugins have either a ticketing system or an email where you can reach out to the company or individual plugin developer for support. Some of the bigger plugins have their own forums where you can ask questions and troubleshoot issues.
Many plugin developers provide documentation on how to troubleshoot plugin problems.
White Screen of Death
When a WordPress website goes down and you get that dreaded blank page, you’re seeing the White Screen of Death. This issue is often caused by a PHP error and can happen when a plugin or theme is corrupted.
The fix:
- try disabling all plugins and switching to the default WordPress theme (right now that theme is Twenty Twenty-Three. If your site uses the Classic Editor plugin, use the WordPress Twenty Twenty One theme instead).
- turn on WP_DEBUG. To do this, you’ll need to feel comfortable with your website’s files. Go into your web host’s panel and look for your WordPress files in the public_html or html directory of your host. If you’re using File Manager on your host, you may be able to edit files. If not, you’ll need to download the file and open it in a text editor or ideally a code editor such as Visual Studio Code. Look for the wp-config.php file. Open it and search for the line: define( ‘WP_DEBUG’, false ); Change false to true. Save the file and/or save it and upload it to your web host using SFTP or the File Manager.
Check your site and you will see the errors displayed. The errors should offer clues as to what is going on.
Once you’ve figured out the problem, go back to the wp-config.php file and change the WP_DEBUG true line back to false. Reupload the file if you need to.
PHP typos can cause the White Screen of Death
Another common reason a site will go down is if you edited theme or plugin files and made a typo in PHP.
When it comes to errors, PHP is very unforgiving. If there’s an extra space or a missing semicolon, your site will go down.
First, it’s not a great idea to touch theme files on a live website. You’ll want to work with a child theme and edit theme files there, and it’s best to edit on your webhost’s staging site or a local site on your own computer, not a live production site. There are recommended ways to extend plugins or change them, and they don’t involve touching the plugin’s code directly.
Even if your theme is a custom theme, it’s best to work with the code somewhere else first. Once you’ve fixed or changed it and tested the changes, then upload the changed files to your website.
Website looks strange
Has it ever happened to you that your website looks like it’s in plain HTML?
The likely cause:
Your CSS stylesheet isn’t loading properly. For instance, if you use Elementor and you just updated the plugin, sometimes there is some wonkiness.
What to do:
- Go to Elementor > Tools > Regenerate CSS. Clear the cache and see if that resolves things
- Clear your site’s cache and your web hosting cache if the problem lingers.
- Make sure there are no errors in your CSS
- Clear your own browser cache and check your site in Incognito mode or in another browser
Other possibilities
- A server connection problem. This usually resolves fairly quickly.
- A WordPress plugin conflict (see above for plugin troubleshooting tips)
Problems with older themes
In my experience, when a site starts looking bad, the theme could be the culprit.
For instance, when I set up this site, I used an older GeneratePress theme I found in the Site Library. Because of changes to the structure and CSS of GeneratePress themes, I ran into issues when I updated part of this site to the new container system from the old container legacy layout system.
The original theme was built with a CSS Grid layout. The new container system uses CSS Flexbox, a different approach.
My menus didn’t look right, and headers on my pages didn’t display properly. My blog’s CSS was completely borked.
To solve these issues, I read documentation and watch tutorials to catch up on how GeneratePress Premium Elements work in 2023. I’m continuing to update parts of the site so it works properly with WordPress’s block editor.
Very old themes
Another issue I’ve seen is with very old themes, circa 2009 or 2010. They were built before themes used WordPress’s Customizer and they don’t do well with new PHP versions.
The code in these old themes is out of date and they were often built using older JavaScript plugins such as Superfish. The structure of these themes is complicated compared to today’s themes. There are often option pages and shortcodes for CSS. The theme developer has usually abandoned the theme and it’s a labour of love to keep them going.
WordPress Debugging Resources
WordPress FAQ Troubleshooting
Feel free to get in touch if you need help troubleshooting your WordPress website.
