How I Debug in WordPress: A Detailed Guide to My Process

Overview of WordPress Debugging

Whether it’s for a client or for our own work, we often need to debug/investigate various problems. From my experience, I’ve shared here how I try to quickly debug and find the possible cause or solution of a problem.

Essential Plugins for Debugging

👉 Simple Admin Language Change

If the client’s website is in another language, it takes time to find the necessary settings. In such cases, installing any of the above plugins allows you to switch the admin language to English with a single click from the Admin Bar. This makes it quick to find the necessary settings.

👉 Query Monitor

An amazing plugin! This plugin provides a lot of information, with many features that are hard to summarize in a few words. If you haven’t used this plugin, you should install it and explore its features.
This plugin should definitely be installed before starting debugging.

Some basic use cases are:

• If there are any PHP Errors/Warnings on the current page, it will display them in red in the Admin Bar with information. Clicking on the Admin Bar reveals where the Error/Warning is located, making it easy to detect them quickly.
• If there are any Errors/Warnings from an Ajax Request, it will notify with a red mark in the Admin Bar.

👉 WP Debugging Plugin

Due to PHP version compatibility or other issues, sometimes a site feature doesn’t behave as expected. In that case, I install this plugin.
If WP_DEBUG isn’t enabled on the site, activating this plugin automatically enables debug mode, and with the “Debug Quick Look” menu on the Admin Bar, you can easily check the site’s log.

This way, you can easily identify where a problem exists by looking at the logs, making it easier to find possible causes.

👉 Health Check & Troubleshooting Plugin

Even after following the above steps, often no clue can be found about the problem. Then this plugin is great!

Using this, you can activate the WordPress default theme with a single click and “Deactivate” all other plugins, and the best part is – the plugins/themes will only be “Deactivated” for the “Admin”, they will have no effect on the visitors!

Using this plugin, first switch the “Theme” one by one and check the site to see if the problem is coming from the theme. If not, then activate the plugins one by one to find the culprit plugin.

After finding the culprit plugin, disable the Troubleshoot mode to bring the site back to the previous state, i.e. the theme and plugins that were active before. This way, you can quickly detect which theme/plugin is causing the problem.

👉 Plugin Detective – Troubleshooting

This is an alternative plugin to the Health Check & Troubleshooting plugin, and it’s also very useful!

Common Debugging Steps

👉 Check Browser Console

If you think the problem is related to browser interaction/JavaScript, first check the browser console on the page where the problem is. For example –

• Slider is not working on the frontend.
• After clicking the “Load More” button, posts are not coming up. etc. If there are any Errors/Warnings in the console, you may find the possible cause there, so you don’t have to spend time checking other things.

👉 Permalink Flush

Sometimes, visiting the single/details page of a custom post type may show a 404 Not Found error. Many times, after checking the code for the plugin/theme, I find no issue. However, simply flushing permalinks resolves it with a single click.

Though plugins usually programmatically flush permalinks after registering custom post types, sometimes it might not flush correctly. Therefore, whenever I find a page showing a 404 error instead of the expected content, the first thing I do is flush the permalinks. One common permalink-related problem is:

• After creating a template with the Elementor plugin, sometimes content won’t appear on its “View/Details” page. Most of the time, flushing permalinks solves this

👉 Clear Cache

When everything is done and you’re feeling mentally 😣 hung up with no clues, I check if there is any caching plugin on the site, and if so, I clear the cache. After investigating a lot, sometimes it turns out that the problem was in the cache!

👉 Make Sure That The Plugins / Themes are Updated

If any problem is found with a plugin/theme, you need to make sure that the plugin/theme is in the latest version. Because the plugin/theme developers constantly update and solve various problems.

It may also be possible that the problem we are facing has already been solved in the latest version.

Advanced Debugging Techniques

👉 xDebug Extension

During development, I often debug using var_dump/print_r functions. Instead of going to the page repeatedly to check var_dump/print_r, you can use xDebug to check variables/functions even better directly within your IDE.

Details: https://xdebug.org/

👉 Understanding PHP Errors

PHP errors in WordPress typically fall into three main categories: parse errors, fatal errors, and warnings. Parse errors occur when the PHP parser encounters syntax issues, preventing code execution. Fatal errors signal critical problems that halt script execution, while warnings indicate non-critical issues that don’t stop the script but may point to potential problems.

To diagnose these errors, enable detailed debugging in WordPress by modifying the wp-config.php file. This logs all errors, warnings, and notices to the wp-content/debug.log file. Tools like the WP Debugging plugin simplify the process by providing a user-friendly interface to view and manage the debug logs. Analyzing these logs helps identify the root cause, whether related to a plugin, theme, or core WordPress component, allowing you to make the necessary corrections.

👉 Check Body Tag’s Class / WooCommerce Product’s Grid CSS Class

When on the frontend page, you may need some information. For example-

• Whether the page we are on is a “Post” / “Page” or a “Custom Post Type”.
• Which theme is currently active on the site.
• ID of the “Post” / “Page” or “Custom Post Type”.
• The “Template Type” of the page, such as: Archive, Single, Author etc.
• Whether the page is loaded from a custom template file, such as theme-name/template-about-us.php.
• You can look at the classes in the body tag to get more information.
• Additionally, you can get the following information from the WooCommerce product class –Product ID, Stock Status, Product Category, Product type, Tax info and more.

From the body class of the page and the class of the WooCommerce product loop, in addition to the information mentioned above, you can also get a lot more information that is useful during debugging.

Footnote:

• Even after following the mentioned topics, the solution to a problem may not be found. But I think the above topics will help speed up the debugging process 🙂

This is just my debugging process. Each person has their own approach and tools. If you have any personal techniques or tools you use daily, feel free to share in the comments. It might be helpful for me and others who see this post.