Local Community

Local + Xdebug + VSCode mostly working in 2022 but cannot connect to Local site through port 9000/9003

Spent most of yesterday fiddling with Xdebug trying to get it to work. It used to work perfectly but at some point in the last 2-years it’s broken. I’m 90% there but there’s one more thing I need to fix.
I’m using a Mac running macOS Monterey and Local 6.4.3.
Here’s how I got it 90% working:

Firstly, to clarify:

  • Any site using < PHP 7.4 uses Xdebug 2 on port 9000 in Local.
  • Any site using > PHP 7.4 uses Xdebug 3 on port 9003 in Local.

I was able to get the code stepper to work by using the following Local settings:

  • Local > Preferences > Advanced > Router mode > Site Domains

and then using the following site settings:

  • Web server: nginx (not sure this is important)
  • PHP version: 8.0.22
  • Database: MySQL (not sure this is important)

I have been using the Xdebug + Local extension, which can be found here: GitHub - pixeljar/local-addon-xdebug-vscode
It certainly helps as a one-click solution to create the required .vscode folder with the launch.json file inside but it’s not currently fully compatible with Xdebug 3, so I’ve tweaked the output. I’ll get to that in a minute.

Moving to VSCode, you need to have this PHP Debug extension installed and activated: PHP Debug - Visual Studio Marketplace

I’m not sure if this next bit is needed but I installed PHP 8 at the system level (since it’s no longer installed by default in macOS Monterey). I did this using brew install php, which installed version 8.1.10. I felt this was close enough to Local’s version of PHP but you can specify other versions if you need to. This put a php executable at /opt/homebrew/bin/php so I added this to my settings.json file in VSCode in the following way:

"php.debug.executablePath": "/opt/homebrew/bin/php", "php.validate.executablePath": "/opt/homebrew/bin/php"

If you use the Xdebug + VSCode extension in local, clicking the link under Tools > Xdebug + VS Code > Add run configuration to VS Code will add the required .vscode folder and launch.json file.
I’ve then edited this to use port 9003 instead of 9000 as Xdebug 3 uses port 9003 where as Xdebug 2 (which the extension supports), uses 9000.

Moving to the php.ini file, which’ll need modification. This can be found in site-folder > conf > php > php.ini.hbs where site-folder is the folder of your site, which can be reached by clicking the ‘Go to site folder’ under the name of the site in Local. I’ve removed all the xdebug. settings that Flywheel added and have replaced with the following. I’ve added this below the entries for opcache but before the [Pcre] entries:

{{#if os.windows}}
zend_extension = php_xdebug.dll
zend_extension = {{extensionsDir}}/xdebug.so

xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.idekey = VSCODE

The crucial part, I found to making the code stepper work in VSCode was the xdebug.idekey = VSCODE line. The other two lines should replace all the other lines that Local usually adds for Xdebug 2, with these more consolidated lines which are for Xdebug 3.

After saving that and restarting the site in local, you should be able to debug by opening the /app/public folder in VSCode, adding a breakpoint, and then pressing F5 to run Xdebug. If it then shows a pop-up with some options, choose ‘PHP’. Then open the site using the site domain (e.g. https://your-site.local). It should pause in VSCode when it hits the breakpoint, providing that it does.

Using the above, I was able to get everything working except for using http://localhost:9003 for debugging. When visiting this page, it just constantly tries to load but never does and never times out. Interestingly, I think this is related to how Local connects to localhost in general as, using Gulp and http://localhost:3000 for browserSync has recently stopped working too. It’s like Local doesn’t want to forward the site through localhost anymore, even though it was working around a month ago. Everything else seems to have stayed the same in my dev set-up so it’s possible a recent update to Local, or macOS has caused an issue.
If anyone knows where the problem might be, please let me know.

Hope the above helps someone.

1 Like

There is an error in logs/php/error.log which reads:
[14-Sep-2022 08:53:15 UTC] Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port) :-(

This is good in a way, in that it’s telling me it’s trying to connect on the correct port, but doesn’t explain why it can’t route port 9003 on localhost through to site-domain.local.

When adding "log": true to below the port in the .vscode file, I can see more output in the Debug Console of VSCode. I can see that it is trying to connect on port 9003 and when I try and load localhost:9003 in my browser, I see the line: new connection 1 from ::1 appear but nothing more happens, it just constantly tries to load.

I’ve found that adding path mappings, such as:

"pathMappings": {
  "/app/public": "${workspaceFolder}"

just completely break the stepper so haven’t added them to my .vscode file.

Here is my settings php.ini.hbs and settings.json information.

You’ll notice a difference in the pathMappings.

These are in the user space, not the workspace space.

Thanks. I’ve added the pathMappings and restarted everything but it hasn’t made any difference - localhost:9003 still never loads.
I’ve been using the .vscode > launch.json file as that’s the one added by the Local + VSCode extension. Do you think it’ll make any difference if it was in the User > settings.json file? I can’t image so personally as that won’t fix the similar issue with Gulp browserSync on localhost:3000.

By putting it in the User settings you don’t need to add it on a workspace by workspace basis.

Other thing to try is switching router mode in Settings from localhost mode to site domain mode.

That’s a good tip. I’ll do that to save having to do that on every site.

I do already have the Router mode set to Site Domain. I remember I couldn’t make localhost work in that setting when it came out have always stuck with Site Domains.

Like I say, it was working up until ~a month ago. It didn’t work on my old MacBook Pro. I then upgraded to a Mac Studio which arrived in June and localhost:3000 was working just fine with Gulp. Since then, it’s stopped working. Other than a security update for macOS, the only other real thing I can think of is a recent update to Local has broken something somewhere. It probably isn’t broken for all users either, just to complicate matters.

I don’t know if anything on Local runs on port 3000

Oh, I know nothing from Local runs on port 3000 but I have Gulp running which proxies the site through browserSync and delivers it on port 3000 so that CSS changes are injected without having to reload the site. As this was working back from June until recently, I feel this is probably related.

Hello! I’ve the same problem! Since I’ve updated, I can’t manage to make it work xdebug. I’ve changed the settings user and phpini, Thanks @afragen, but I don’t know what to make more. Not working. How could we debug that the installation is correct and settings as well?

I think I solved following the @jackmcconnell instructions. Thanks!

1 Like

Hey all,

Just dropping in here to say that Pixel Jar released a new version of the Xdebug + VS Code add-on within Local this week. This includes commits from @afragen for full support of Xdebug 3 - if anyone is running into issues, I’d recommend updating to that latest version. Hopefully that should make things work better out of the box with less manual tweaks!



Hello, I just registered here because after updating the plugin (I updated because I wanted to make the debugging quicker), debugging doesn’t work any longer. I was debugging with 1.0.6 just 2h ago and after the update, it immediately didn’t work. I tried to fix it and don’t know what to do. I then saw that just a week ago this version has been made available after 2 years of the last version. So, I think there have been major changes?

Using V1.0.6 it worked:
The site in question runs PHP 7.4.1
I did the simple installation (extension, add launch config, “Listen for XDebug”) and it worked. But now, there are two entries in “Listen for”. None of them work.

Do you know what the problem might be?
Thank you

I found the solution and think that you guys need to change the entries that get automatically written into the php.ini.hbs.

My path to the solution:


xdebug.scream = 1
xdebug.show_local_vars = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 1
xdebug.idekey = VSCODE


; Settings for Xdebug 2.x
xdebug.scream = 1
xdebug.remote_enable = 1
xdebug.show_local_vars = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 1

; Settings for Xdebug 3.x
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_port=“9000” ; Default now is 9003

I hope this will help. Anyway, thank you for this add-on, it works great once it works :slight_smile:

1 Like

Thank you for the solution, jackmcconnell!

FYI, switching PHP ver. down to 8.0.22 was all I needed to get it to work.
(previously, I started from the latest comments and tried changing the settings in php.ini.hbs - but did not help. Switching to PHP 8.0.22 required no additional fixes)