How to understand and navigate through magento errors with Xdebug


At Ampersand, our chosen ecommerce platform is Magento 2. One of our Junior Developers, Sharon, shares some insights on how to navigate through errors with Xdebug.

Debugging is the process of detecting and removing existing and potential errors/bugs in software code that can cause it to behave unexpectedly or crash. Magento can have quite vague errors or give no errors as to why something isn’t working as expected. Xdebug is an extension for PHP, which provides a range of features to improve the PHP development experience.

Once Xdebug has been installed and configured in your IDE (PhpStorm), you can start interactively debugging CLI commands, web requests, and code. Debugging is done by setting breakpoints at certain lines of your code and telling IDE (PhpStorm) to listen for incoming connections. When PHP executes a line that has a breakpoint on it, Xdebug will step in and pause execution, allowing you to gain valuable insight into all that is happening during execution. Breakpoints are set by clicking in the left-hand gutter of the code, along the line at which you want to break:

While working on the debug window, there are various buttons for controlling the execution of the code. They are listed in the table below with their respective icons and descriptions.

A key aspect of debugging which is very helpful is to inspect and watch a variable, expression or function’s value all the way through the execution of a request to see when it changes. In PhpStorm , you can add variables to a separate “Watches panel” , this separates these variables from all the data in the main “Variables” panel.  There are two ways to add variables to your watch list:

  • Right-click the variable in the file during debugging and selecting Add to Watches 
  • Right-click the variable in the “Variables” panel and select Add to Watches.


To start debugging, considering that a server needs to connect to our machine, we need to inform the server about our intent. This can be done in several ways:

  • Append the GET parameter or the POST variable – You can append the following parameter XDEBUG_SESSION_START=PHPSTORM, for instance In that case the server will issue a cookie that will be set in response. This can be used to debug various scenarios such as
    • Debugging an API call error
    • Debugging a Graphql query error
  • Set the cookie manually – You can set the XDEBUG_SESSION cookie manually to enable the debugging session.
  • Debugging with Xdebug Chrome extension – this is an easy debugging, profiling and tracing extension for Xdebug

Enable the extension in Chrome as shown in the following figure.

  • In Chrome, right-click de-bug in the Chrome toolbar.
  • From the pop-up menu, click options.
  • From the IDE Key list, click PhpStorm.
  • Click save.
  • Open your PhpStorm project.
  • In the top navigation bar, click start listening.
  • Finally, refresh your page and after some time you should see a debug window appear in PhpStorm. If it is your first time connecting, you will be asked about accepting debug connections.
If you’re interested in developing your career and learning more about Magento 2,  head to our careers page to view all of our current engineering opportunities.