blog: xdebug understanding and troubleshooting

[rfay]

The Issue

XDebug troubleshooting blog along with new v1.25 debugging feature

Rendered at https://pr-520.ddev-com-fork-previews.pages.dev/blog/xdebug-step-debugging-understanding-and-troubleshooting/

[github-actions]

🌐 Fork Preview for PR #520

https://pr-520.ddev-com-fork-previews.pages.dev

This preview updates automatically when you push changes to your fork.

[rfay]

It's pretty tedious how much is in here.

[tyler36]

While reading through the blog I noticed the following line:

ddev config global --xdebug-ide-location=wsl2

I'm not sure thats 100% true. When I check my settings, I don't appear to have this but debugging works for me.

$ ddev -v    
ddev version v1.25.0

$ /usr/bin/cat ~/.ddev/global_config.yaml| \grep --color=auto xdebug
xdebug_ide_location: ""
...

Was debugging all week using 1.24.10 (various HEAD) without issue (only updated today).

VSCode: 1.108.2 "Running in Ubuntu 24.04 (WSL2)"

** Update

Playing around some more.

So I use PHP extention which includes php debugging.
When I use PHP Debug, I get firewall issues (host.docker.internal [192.168.127.254] 9003 (?) : Connection refused).

[rfay]

Thanks so much @tyler36 ! Could you give me a screenshot of your project? The assumption here is use the WSL extension, which runs a proxy in the WSL distro. If you don't do that, then it will definitely use the alternate technique. I don't have WSL2 machine with me today...

[tyler36]

Did some more testing this morning on a portable version of VScode and Ubuntu 25.04.
VSCode: 1.109.0 Running in Ubuntu 25.04 (WSL 2)
- WSL Extenstion: 0.104.3

• Testing using Drupal 11 quickstart guide.
• ~/.ddev/global_config.yaml contains xdebug_ide_location: ""

Xdebugging

PHP Debug

• ✅ 1.40.0 working with launch.json
• ❌ 1.40.0 not working when the hostname line is missing.

    {
        "name": "Listen for Xdebug",
        "type": "php",
        "hostname": "0.0.0.0",
        "request": "launch",
        "port": 9003,
        "pathMappings": {
            "/var/www/html": "${workspaceFolder}"
        },
        "preLaunchTask": "DDEV: Enable Xdebug",
        "postDebugTask": "DDEV: Disable Xdebug"
    },

PHP

• Disabled PHP Debug and reloaded window.
• ✅ 1.66.18408 WITHOUT hostname (as shown below)
• ✅ 1.66.18408 with hostname enabled but schema reports "Property hostname is not allowed."

    {
        "name": "Listen for Xdebug",
        "type": "php",
        // "hostname": "0.0.0.0",
        "request": "launch",
        "port": 9003,
        "pathMappings": {
            "/var/www/html": "${workspaceFolder}"
        },
        "preLaunchTask": "DDEV: Enable Xdebug",
        "postDebugTask": "DDEV: Disable Xdebug"
    },

• On my main WSL, hostname was removed as I typically use PHP extension
• PHP Debug ONLY works with "hostname": "0.0.0.0"

ddev utility xdebug-diagnose

On my initial test with PHP Debug ddev utility xdebug-diagnose reported fine.
PHP also reported fine. When I switch back to PHP Debug, ddev utility xdebug-diagnose starting reporting.

"Xdebug: [Step Debug] Could not connect to debugging client. Tried: host.docker.internal:9003 (fallback through xdebug.client_host/xdebug.client_port).
○ Port 9003: No listener detected "

I've tried disabling/enabling the extensions and starting/stopping the debugger but sometimes it appeared and sometimes didn't.

Finally figured it out. If VSCode Debugging is listening (active) AND window is reloaded (Developer: Reload Windows) WITHOUT stopping the debugger, the warning appears. Starting and stopping a new debug session clears the Could not connect to debugging client. from ddev utility xdebug-diagnose.

So I'm able to replicate and resolve both the issues. And more importantly, debug with both extensions.

[rfay]

Wow, awesome. I never knew exactly what the PHP extension was vs "PHP Debug", which is maintained by the Xdebug folks (or folk).

In VS Code/PHP Debug the hostname: "0.0.0.0" tells VS Code to listen on all interfaces, not just localhost, which is important because unless using Mirrored Networking, the network interfaces are many, and if VS Code doesn't listen on all, it won't get the message.

However, another extension may just do that because it's the thing to do, not requiring that.

[rfay]

TODO:

• Move the ddev utility xdebug-diagnose section way up to the front.
• Try to trim things down so this isn't so incredibly verbose.