xdebug_could_not_connect_wsl_docker.md

Fixing Xdebug Connection Issues in Docker with VSCode on WSL

The Problem

When running Xdebug in a Docker container with VSCode on WSL, you may see this error in your logs:

[php:notice] [pid 21:tid 21] [client 172.23.0.1:54372] Xdebug: [Step Debug] Could not connect to debugging client. Tried: 172.23.0.1:9003 (from REMOTE_ADDR HTTP header), host.docker.internal:9003 (fallback through xdebug.client_host/xdebug.client_port).

Why This Happens

Xdebug running inside the Docker container is trying to connect back to your IDE, but VSCode's PHP debugger by default only listens on 127.0.0.1 (localhost). Since the Docker container is on a different network, it can't reach localhost.

The Solution

Update your VSCode launch.json to listen on all network interfaces:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen with XDebug",
            "type": "php",
            "request": "launch",
            "pathMappings": {"/var/www/html":"${workspaceFolder}"},
            "port": 9003,
            "hostname": "0.0.0.0", // <-- ADD THIS LINE
        }
    ]
}