wp-local-docker-v2: Xdebug Not Working with Windows 10, WSL and VS Code
Describe the bug I just started using WP Local Docker, so thank you so much for developing such a great resource. Since I’m not super familiar with Linux and Docker, it’s taking me some time to get up to speed. The good news is that I’ve got most things configured at this point. The only item I can’t figure out is Xdebug.
When I try to run debugging using VS Code, breakpoints don’t work and I get this message in debug.log on every page load:
Xdebug: [Step Debug] Could not connect to debugging client. Tried: 10.0.128.3:9003 (from HTTP_X_FORWARDED_FOR HTTP header), host.docker.internal:9003 (fallback through xdebug.client_host/xdebug.client_port) :-(
I’ve used Xdebug a lot in the past, so I’m pretty confident I know how to use it generally, but I can’t seem to get it working with Windows 10, WSL and Docker. Can you give me any advice?
Thanks a ton.
Environment information
- Device: Acer Laptop
- OS: Windows 10 with WSL
- Docker Desktop version: 4.5.1
- Browser and version: Chrome v99.0.4844.51
- WordPress version: 5.9.2
About this issue
- Original URL
- State: open
- Created 2 years ago
- Comments: 35 (5 by maintainers)
I was finally able to get Xdebug working with WSL 2, Docker and WP Local Docker. I followed very closely to the steps outlined at https://github.com/10up/wp-local-docker-v2/issues/294#issuecomment-1073308040.
Here are the steps I followed in case this will help someone else:
ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'/config/php-fpm/docker-php-ext-xdebug.iniwithin the WP Local Docker website you’re working on. Setxdebug.client_hostto be whatever IP address was returned in step 2. For example, the final line might look likexdebug.client_host = 192.168.119.150. Until we can find a better solution, you’ll need to repeat steps 2 and 3 every time WSL 2 restarts.10updocker stop allin the WSL 2 terminal.10updocker start env-namein the WSL 2 terminal. Make sure to replaceenv-namewith the name of your environment.Xdebug: [Step Debug] Time-out connecting to debugging client...take a look at https://xdebug.org/docs/all_settings#start_with_request. It’s likely Xdebug is running on every page load, even if VS Code isn’t debugging.For what it’s worth @LoveDuckie, I didn’t need to change the
Remote.WSL2: Connection Methodsetting in VS Code. It worked with the defaultwslExeProxyoption for me.Thanks again for the help @LoveDuckie and @nicholasio.
This might be an issue with WSL 2 not forwarding ports properly. I can’t provide an in-depth explanation of the issue but here’s how I managed to get XDebug working under WSL 2.
1- Get your WSL 2 IP Adress with
ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'2 - Add a manual host entry to your Windows 10 hosts file that points to that IP (e.g:wsl2.test) 3 - Editconfig/php-fpm/docker-php-ext-xdebug.iniand add/replace the following line:4 - Perform a global restart
10updocker stop all && 10updocker start env-nameKeep in mind that WSL 2 Ip address will change every time you restart your machine or just WSL itself. I know it’s possible to have windows automatically update the hosts file with the correct IP address but I haven’t managed to get that running.
FWIW: I think we would not have this problem if we were running the docker daemon inside WSL 2 directly instead of Docker Desktop.
@jg314 Thanks for the super fast response!
I’ll definitely let you know if I find a fix. I think the problem is something to do with port-forwarding between the Visual Studio Code process running in windows, and the extension listening on port 9003 in WSL2. Not 100% sure what the problem is but I think I’m sort of close.