Local Community

xDebug + Local v6.4.3 + macOS not running

Bug Summary

xDebug does not appear to run (as viewable in the Call Stack) with xDebug + Local v6.4.3

Steps to reproduce

Update to the latest version of Local
Try using xDebug (on a new site or old one)

Environment Info

Describe your environment.

  • What Operating System are you using? macOS 12.6
  • What versions of site software (Nginx, Apache, PHP, MySQL) is used? PHP 8.0.0, MySQL 8.0.16
  • What version of Local is installed?v6.4.3

Supporting info

Please provide your Local Log. See this Community Forum post for instructions on how to do so:

Include any screenshots or video recordings of the issue to help others reproduce.

Set this up with a completely fresh macOS user but still nothing.

Hey @scottbuscemi – Thanks for bringing this up!

Anytime I’m using Xdebug’s step debugger, I always feel like I’m casting a complicated spell. That being said, let’s see how we can help!

The first thing I’m curious about is what editor you are using to connect to Xdebug?

When troubleshooting this, the main thing to keep in mind is that the newer versions of lightning services are using Xdebug 3.x whereas the older PHP versions were typically using 2.9.x. Because Xdebug’s default port was changed from 9000 to 9003, you’ll likely need to adjust a setting with the various configuration files.

I bring that up because I notice that you mentioned using PHP 8.0.0. I ran a few tests to try and replicate the issue.

For these tests, I used these settings:

  • M1 mac
  • The “Xdebug + VSCode” addon installed from within Local (ie, I wasn’t running it from the master branch
  • Latest stable Local, 6.4.3

For PHP 8.0.0, I was able to get it working with the above settings out of the box. Note that the 8.0.0 version of PHP is still running Xdebug 3.0.0, but using Port 9000.

For PHP 8.0.22, I had to update the launch.json file to use port 9003 instead of 9000. But otherwise it worked.

For troubleshooting this, I’d recommend looking at a few places:

  • For the server side and PHP’s settings, click the “i” button next to the PHP version in Local. This will open the phpinfo() for the site. You can search for Xdebug to find those settings, and in particular, the xdebug.client_port setting. Newer versions of Xdebug should have a value of 9003.

  • For the editor side (I used VS Code) open the .vscode/launch.json file and verify that its port value is the same as the one in Xdebug.

One thing I did notice while testing, was that the latest code on the master branch of the Xdebug + VSCode addon has a configuration option to use that default port of 9003 (thanks @afragen for that commit! ). I think that should new item should make most things work out of the box, so I’m creating a task for us to publish a new release of that addon to the Addon Library. That way users that install the addon from within Local will get that latest change.

Anyway, that’s a lot of info, but hopefully it gives you a little direction of where to look to troubleshoot. Let us know a little more detail about what you’re trying and what editor you’re using, and we can help take a closer look!

1 Like

I had a quick call with Scott and the missing piece was having an xDebug extension installed for each browser and ensure the IDE_KEY of the browser extension is set to VSCODE

He ultimately had everything else set up correctly.


Hi, i have the same problem here.
Using Local v6.4.3 and PHP 8.0.22 (it’s working when using PHP 7.4.1), i really don’t get it.

I try all the settings in the comments above but still not working on my side.

From my side, i just want the dump rendering to be clean (don’t really use it inside VSCODE and step debugger)

Somebody can help please?
It was working with the previous version of Local.

Thanks for pointing that out @jcs – You can edit the php.ini.hbs file to include develop in the xdebug.mode line and then restart the site in Local:

I’ll create a bug so that we get this included for future sites, but for now, you’ll need to manually make that change.

@ben.turner Thanks for the tip, it helps me to solve that.
I was adding the develop mode in the wrong file (i was targetting conf/php-8.0.22/php.ini.hbs instead of conf/php/php.ini.hbs)


Hello @scottbuscemi and all!

Thank you very much for bringing all of this to light and providing so many details - it is very appreciated.

This bug has been passed along to the Local development team and is queued to be addressed in an upcoming sprint.

We will keep you updated. In the meantime, please refer to Ben’s manual fix above. :point_up_2:

Thank you,

Sam :woman_technologist:t3:

Hi all,

The issue that @jcs and @ben.turner were discussing has been resolved with the latest release of Local, v6.5.2 - www.localwp.com/releases/6.5.2

If for some reason you’re not seeing the correct debug,develop in your php.ini file, try changing the PHP version to a different value on the site overview page and then change it back again (i.e., change it to PHP 8.1.9, then immediately change it back). This will force Local to grab the updated config file if it didn’t automatically.


I’m still unable to get xDebug to work without running a browser extension to set the xDebug cookie.

In other words, xDebug can’t be used for background tasks or cron jobs anymore. Previously, I could simply enable xDebug within VSCode and it would start tracking against any queries.

Is that not possible anymore? @austinwendt

Hi @scottbuscemi - great question! This one was fun to dig into :thinking:

This is controlled by the xdebug.start_with_request setting. We found a commit from August that changed this value from yes to trigger, which is what you describe - Xdebug has to be triggered when before it was just on.

Immediate fix - this setting can be changed in your php.ini file by setting xdebug.start_with_request=yes in the site config (Local Sites/{site_name}/conf/php-{version}/php.ini.hbs) .

I’ll chat with the engineering team as it isn’t clear if this was inadvertent or if we made that change for a reason. My hunch is we just need to set that value back to “yes” by default. Thanks for catching this!

More context, I’ll just share here because it is relevant to the thread:

I’m assuming we turned it off by default because Xdebug was affecting site performance, and we’d rather users opt in than opt out. With the next release of Local (hopefully next week or two!), we’ll be adding an Xdebug toggle to the Site Overview page to very quickly turn Xdebug on or off. No more going into the php.ini file if you want to disable it. It is there when you need it; when you don’t, you can disable it so it isn’t affecting performance.

Since users will be able to very quickly turn it off, I think it makes sense to enable by default again.

You solved it. You did it :sob:

Thank you. This was not noted in the documentation/changelog anywhere, and is the difference between being productive and not being productive at all. The past 2 months has been rough.

:heart: I’m really sorry; any time Local gets in the way of being productive means we let you down. I just want to acknowledge that isn’t lost on me and the team.

I don’t think it was an intentional change, which is why it slipped through a change log. I’ll try to get to the bottom of how that made it through without us noticing.


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