[Bug]: Xdebug with trigger causes 502 Bad Gateway

[mjblacker]

Platform

Windows

Operating system version

Windows 10 22H2

System architecture

Intel (x86)

Herd Version

1.6.1

PHP Version

No response

Bug description

When xdebug is enabled with trigger based debugging it will try to change the port for the fastcgi daemon by adding 100 to the base port. (There is a config option for this but doesn't do anything from what I could find)

The windows php-cgi processes are already running on the base port + version number so adding 100 just gives a 502 Bad Gateway error as there is no fastcgi available on the port trying to be accessed.

To fix:
Edit the debug.conf file in the ~.config\herd\config\pro\nginx folder and either negate the map for detecting the xdebug cookies or change the debug ports to match the base ports.

Steps to reproduce

Turn on xdebug but do not enable for all requests, use a browser plugin to trigger the debug session as needed.

Relevant log output

nginx-error.log:

2024/05/14 16:49:08 [error] 13592#19976: *1 connect() failed (10061: No connection could be made because the target machine actively refused it) while connecting to upstream, client: 127.0.0.1, server: xxxx.test, request: "GET / HTTP/1.1", upstream: "fastcgi://127.0.0.1:9183", host: "xxxx.test"

[mpociot]

@mjblacker do you use Herd Pro?

[mjblacker]

@mjblacker do you use Herd Pro?

No.
Followed these instructions: https://herd.laravel.com/docs/windows/1/advanced-usage/xdebug
Only enabled the mode though not the start commands.

Already had a workflow for using xdebug so wanted to use it as I would if I was using local, docker, artisan serve.

Might also be an issue with all requests IF you are using the browser extension like me as the nginx rule is just based on the cookie.

Plugin I'm using:
https://chromewebstore.google.com/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc

The reason the "pro" file is included is from the base nginx file in the config includes it and the valet file.

From the bottom of the ~/.config/herd/config/nginx/nginx.conf

include "C:/Users/xxx/.config/herd/config/pro/nginx/*.conf";
include "C:/Users/xxx/.config/herd/config/valet/Nginx/*.conf";
include herd.conf;

[mpociot]

Right - that's a bug in Herd in this case. With Herd Pro we automatically switch to the debug FPM process based on the triggers. But as you're not using Herd Pro, the pro config should not be loaded.

So you can fix it yourself right now by removing/commenting out the line that includes the pro configuration file.

[dev-idkwhoami]

So i have the same issue i followed the instructions in the Herd docs to activate xdebug.

Then i found this issue and tried commenting out the "pro" inclusion, but that was a bad tip since the nginx variable herd_sock is being mapped in "C:\Users<user>.config\herd\config\pro\nginx\debug.conf"

So all that did was break Herd even more ^^

Edit:

I just bought Pro just for the fun of it and with Pro this actually just works 🤨

[mjblacker]

So i have the same issue i followed the instructions in the Herd docs to activate xdebug.

Then i found this issue and tried commenting out the "pro" inclusion, but that was a bad tip since the nginx variable herd_sock is being mapped in "C:\Users.config\herd\config\pro\nginx\debug.conf"

So all that did was break Herd even more ^^

My original solution to fix (as I posted this bug after figuring it out)
Edit the debug.conf file in the ~.config\herd\config\pro\nginx folder and change the debug ports to match the base ports.

Glad that it's all working with Pro though.

[EMeDesign]

I have the same issue after using xdebug and xdebug-browser-extension (I don't have herd pro).
I tried to reinstall herd, edit config like above but still get 502 code.

Finally I find I forgot to flush the cookie of my site in browser😂.
Hope other people will not forget this.

[weidmaster]

So i have the same issue i followed the instructions in the Herd docs to activate xdebug.
Then i found this issue and tried commenting out the "pro" inclusion, but that was a bad tip since the nginx variable herd_sock is being mapped in "C:\Users.config\herd\config\pro\nginx\debug.conf"
So all that did was break Herd even more ^^

My original solution to fix (as I posted this bug after figuring it out) Edit the debug.conf file in the ~.config\herd\config\pro\nginx folder and change the debug ports to match the base ports.

Glad that it's all working with Pro though.

I had the same issue and got confused with the base ports. Thanks for the solution, and for everyone who get confuse, the base port is the default port specified in the file.

map "$xdebug_present" $herd_sock {
    default "127.0.0.1:9083";
    #"~^debug$" "127.0.0.1:9183";
    "~^debug$" "127.0.0.1:9083";
}

Note how in my case 9083 is the default port (the base), so I just commented the 9183 and updated the debug to the same 9083. You need to do that for each version you use of PHP (they are listed in the file).

Now, why a pro feature is messing up the Herd free solution is a mystery to be solved. But now Xdebug is working with VSCode and the debugger helper!

[baekkwanghyoun]

/?XDEBUG_SESSION=PHPSTORM
It is working

[mickby]

I am getting the same problem (502)
I edited the config to look like this:

(commented out) include "/Applications/Herd.app/Contents/Resources/config/pro/nginx/.conf";
include "/Users/me/Library/Application Support/Herd/config/valet/Nginx/";
include herd.conf;
include "/Applications/Herd.app/Contents/Resources/config/default-sites/*.conf";
}

Now I get:
2025/10/15 14:10:05 [emerg] 7833#37448: unknown "herd_sock_81" variable

(I am a Pro User)