Xdebug nightmare

Updating Local or PHP version is a nightmare for me, and I guess, for many others… I always have to reconfigure the Xdebug and the PHPCodeSniffer and try many things in different ways to get everything working as before.

Is there anyone suffering like me?!!

Yesterday, I have updated the Local to version 7.2.1+6433, and updated PHP version to 8.0.30, and started to get this error:

phpcs: Cannot load Xdebug - it was already loaded
ERROR: Referenced sniff "PHPCSUtils" does not exist
Run "phpcs --help" for usage information

I tried everything to make both, Xdebug and PHPCS work with no luck!

Any idea, please?!!

@jafar I’m not familiar with PHPCodeSniffer but have you tried using one of our Xdebug add-ons to see if they work easier for you?

Yes, I’m using the Xdebug + PhpStorm extension.

To clarify you said you run into this issue every time you try to update Local or PHP versions?

That’s right. But this time I’m not able to make it work again.

I don’t know if this is the right approach to fix the issue, but I opened the Local site shell and tried to update Xdebug using this command: pecl upgrade xdebug. It upgraded Xdebug to version 3.2.2, but now I’m getting this message on the site shell:

Xdebug requires Zend Engine API version 420200930.
The Zend Engine API version 420210902 which is installed, is newer.
Contact Derick Rethans at https://xdebug.org/docs/faq#api for a later version of Xdebug.

But running the php -v command shows this info, where the Xdebug version is 3.1.5:

PHP 8.0.30 (cli) (built: Sep 12 2023 17:45:00) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.30, Copyright (c) Zend Technologies
    with Zend OPcache v8.0.30, Copyright (c), by Zend Technologies
    with Xdebug v3.1.5, Copyright (c) 2002-2022, by Derick Rethans

And the same version I get on the phpinfo page:


The version 3.2.2 is not visible to Local and PhpStorm at all:

PhpStorm CLI Interpreters

I tried to uninstall Xdebug in the Local site shell, and reinstall it again, but it didn’t work. I tried that many times, and now, the Cannot load Xdebug error message is getting repeated the same times I reinstalled Xdebug!!

phpcs: Cannot load Xdebug - it was already loaded
Cannot load Xdebug - it was already loaded
Cannot load Xdebug - it was already loaded
Cannot load Xdebug - it was already loaded
Cannot load Xdebug - it was already loaded
ERROR: Referenced sniff "PHPCSUtils" does not exist
Run "phpcs --help" for usage information 

Repeated error message

It seems it keeps adding the Xdebug configurations somewhere without updating the existing ones, and whenever it runs Xdebug, it runs it multiple times.

I have no idea if this is something related to Local or PhpStorm or something else.

Hi, @jafar, and sorry for the issue you’ve encountered here with Xdebug after upgrading Local.

You should not need to upgrade or reconfigure Xdebug after a Local or PHP upgrade.

  • phpcs should continue to work, as long as you run it from a shell opened with Local’s “open site shell”.
  • Xdebug should also continue to work as long as your site URL or project path does not change.

About the pecl upgrade command you ran

When you ran pecl upgrade xdebug you upgraded your system’s version of php’s Xdebug extension, not Local’s. (Even though you ran it from Local site shell. This is because pecl is usually associated with your system php binary, which you can confirm by running pecl config-show | grep php_bin. It is not intended to be used to manage Local’s PHP extensions, which we don’t recommend you upgrade manually.)

If you did not mean to alter your system’s PHP extensions, I recommend reversing the steps you took or resetting your system’s PHP configuration files (the ones listed when you run php --ini from outside of a Local site shell).

About the “Xdebug - it was already loaded” message

You should not normally see this message when upgrading Local or PHP.

If you see phpcs: Cannot load Xdebug - it was already loaded messages when running phpcs from outside of Local’s site shell, such as in a PhpStorm terminal pane, this may relate to the Xdebug misconfiguration in your system’s PHP due to installing Xdebug via pecl there.

If you see that same message when running phpcs from inside of Local’s site shell, please confirm and let us know. It might help us if you could also provide these from a Local site shell:

  1. The output of php --ini
  2. The output of grep xdebug "[full path to the Loaded Configuration File from step 1]"

Again, it’s best to consistently run tools like phpcs from inside of Local’s site shell so that you use Local’s version of PHP. If you run it outside of the site shell, your system’s PHP configuration may impact the output you see. This is because the phpcs.phar file includes a header that tells it to use the version of php in your current environment:

> head -n 1 "$(which phpcs)"
#!/usr/bin/env php
1 Like

I haven’t tried with latest Local version, but I’ve had quite similar issues with Xdebug several times, and took painstaking trials to get working again. Sorry I don’t have details at the moment; just chiming in that this is in fact troublesome.

1 Like

I also usually have problems with Xdebug when updating LocalWP and/or PHPStorm.

This time, what happening is that I have a project where the Xdebug kept working with LocalWP Version 7.2.1+6433 and PhpStorm 2023.2.2 and Windows 11

However, on new projects, doing the exact same setup, the Xdebug wasn’t working.

So, after spending a few hours on it, what worked for me was the following:

1 - Close PHPStorm

2 - In your project, remove the .idea folder from the public folder if you already have it there

3 - In your php.ini.hbs files inside the conf folder set up the Xdebug according to the version your site is using, to discover which version, click on the details link next to the PHP version on the LocalWP UI

V2.X php.ini.hbs setup:


V3.X php.ini.hbs setup:


4 - Initialize the PHPStorm again and re-open the public folder of your project to create a new .idea folder there

5 - Go to Settings > PHP > Debug and disable the following options: Force break at first line when no path mapping specified and Force break at first line when a script is outside the project

6 - DON’T USE the LocalWP add-on to add the Xdebug settings file because it is preventing the Xdebug from working somehow.

7 - Open the file /public/wp-load.php and add a breakpoint on line 20 where we have a condition to check if the ‘ABSPATH’ const is defined.

8 - Click on the Start Listening for PHP Debug Connections button in the PHPStorm toolbar.

9 - Open the home of your site and a new popup should be displayed in the PHPStorm asking you to accept Incoming Connection From Xdebug - check the attached screenshot for reference. Select the public folder in the popup, then click on Accept, and the Xdebug should start to work.

It’s that! These steps helped me enable Xdebug for new projects, hope it helps others in the same situation.


I love you, man! I had gotten all the way to Step 9 on my own but I kept missing this little bit…

Select the public folder in the popup, then click on Accept, and the Xdebug should start to work.

And it made all the difference. Thank you! :raised_hands:


ok, we have a winner!
please stick this comment to the top of this forum because it has saved me many hours.

i also updated my lcoalwp and in result xdebug stopped working, i realy tried everything and nothing helped. so thank you so much!

i think the developers of the PHPStorm + Xdebug addon should implenent your solution


This topic was automatically closed 36 hours after the last reply. New replies are no longer allowed.