Debugging Techniques

Ole

27.09.2022

Like every other developer, we’re often running into issues, where it’s not directly obvious, what exactly causes an error. There are some obvious and generally known approaches to debug these cases. But there are also rather unusual ones, which work surprisingly well in some cases. So over the time, we created a list of ideas to get a better understanding of a problem, which we happily share with you. Most of the ideas are valid in general, some are Magento specific.

1. Check Log Files

The first thing we always do, if an error occurs, is checking the .log files on the server. In {{YourMagentoDirectory}}var/log/system.log, exception.log or other files in {YourMagentoDirectory}}var/log, you usually see a proper description of many errors. If you really don’t see anything related, it might make sense to check the server logs as well. In our setups, these are normally stored at /var/log/apache2/error.log or /var/log/nginx/error.log.

2. Debug via Browser

If the log files did not bring anything up, we use the Chrome dev tools for further debugging. You can open them on every page in Chrome by pressing F12 or by right-clicking anywhere and then choosing “inspect”. First thing to check is the “Console” tab. JS errors are shown there. Next, we open the “Network” tab, clear the current view and load the page again. If you open the current or one of the subsequent requests and take a look at the “Response” tab of this request, you often see errors, which are neither logged nor shown.

These two options are in our eyes the first way to go, as they often already help to find a fitting error message, which helps you find out what is going on. As soon as both did not bring up anything helpful, we take the next step and try to reproduce the issue locally.

3. Local Environments

Locally, we have a copy of each shop running in a Docker environment, which is a one-to-one copy of the live environment. As we have a lot more tools locally than on a running live system and are locally also not afraid of breaking anything, this is a good way to actually find the bug. To see more information regarding an error, we need to make sure, that some general PHP settings are correctly set:

error_reporting = E_ALL
display_errors = On
display_startup_errors = On

Additionally, don’t forget to run your Magento instance in developer mode:

Magento 1: Set SetEnv MAGE_IS_DEVELOPER_MODE true

Magento 2: Run bin/magento deploy:mode:set developer in the console

For some issues, it might also be important to have an up-to-date database, as the bug might have recently been introduced. If all is properly set up and the error is actually reproducible, there are the following methods to continue:

4. XDebug

This should be the first tool of choice. It can be easily included in most of the IDEs and used directly there. With XDebug, you have the possibility to set breakpoints in your code and as soon as you refresh the page, the code stops there, and you can see current values of variables and all data, which is available at this point. You can then step through your code line by line, or also step into function calls to debug further. If you need to debug a file, which is called very often, you can also set conditional breakpoints, which only stop, if a given condition is met. Additionally, you can watch specific variables and see how their values change when you go through the code or evaluate any expression you like at this specific point.

5. Dumping Debugging Data

If you can not use XDebug, you can still see all data you need by dumping and showing it directly in the browser. For that, you can use var_dump($var) or print_r($var, true). Please mind, that this approach is not recommended, but an alternative, if you cannot use XDebug for whatever reason. Alternatively, you can log stuff using the Magento logging functionality. A good explanation, how this is done, can be found in the Magento Docs.

6. Check on a Clean Magento Instance

Try to reproduce the issue on a clean Magento instance of the same version, without any customizations or third party modules. This way, you can at least find out if your problem is a Magento bug or introduced by someone else. For Magento bugs, check out the official GitHub repository. For all other cases, continue with your search.

7. Wolf-Fence-Algorithm

The Wolf-Fence-Algorithm is named after the idea of catching a wolf in a fixed area. You first build a fence, which separates the area in two halves, and find out where the wolf is now. Next thing you do, is building another fence in the half where you spotted the wolf and so on, until there is not so much space anymore, where the wolf could hide. For debugging, this approach is the same. We disable half of our modules (or half of a specific file or whatever we already did to narrow down the problematic area) and check, if the issue is gone. We continue with this approach, until we actually find the problematic module, file or line.

8. What has changed?

We’ve now gone through a lot of practical approaches and obviously, we still did not find the issue. So let’s ask ourselves, what has changed before the error occurred? Even if certain changes often look unrelated, it’s definitely worth a try reverting these changes and checking again, if the issues still persists. A good approach here is to use git bisect to find the exact commit, which introduced the issue. git bisect works with the Wolf-Fence-Algorithm we explained above, but instead of disabling half of the modules, you revert half of the commits and keep on going, until you find the problematic commit.

9. Ask for Help

Often, it helps a lot, talking to your colleagues or even asking for help in the community. You might be surprised, how many people have already run into the same issue and how many approaches there are to solve it. So don’t be afraid to ask for help on StackOverflow or in the Magento Slack channels.

10. Rubberducking

And the last approach, even if it may sound silly, often leads to the solution. Try to explain the problem to a rubber duck. With this approach, you have to structure the whole problem in an understandable way and make it as easy as possible, so that the poor duck understands it. And while doing this, you often come to a new idea or a new conclusion, which helps. If you don’t have a rubber duck, your kids, partner or parents are good alternatives as well.

So far, we never had an issue, which could not be solved after all these steps. If you have another approach, which should be included in this list, let us know.

We hope, we could help a bit and give you a few ideas.