Xdebug: [Step Debug] Could not connect to debugging client
When upgrading from Xdebug 2 to version 3, the most immediate hurdle isn't the new featuresâit's the connection handshake. If you are seeing the error [Step Debug] Could not connect to debugging client, the issue is almost always a mismatch between how the host container (your IDE) expects to connect and where the PHP process inside your Docker container is actually listening.
The specific error Tried: host.docker.internal:9001 indicates that Xdebug 3 on your host machine has successfully started, but it cannot establish a TCP connection back to the client. In your scenario, you are running a Linux host (Fedora 33) with Docker and PhpStorm. The failure occurs because the PHP process inside the container attempts to connect to host.docker.internal:9001 to initiate the debug session, but the firewall or network routing prevents this specific connection from reaching the IDE.
The Architecture Shift in Xdebug 3
In Xdebug 2, the model was "server-driven." The PHP script would wait for a request (triggered by xdebug.remote_enable=1 and remote_autostart) and then actively initiate a connection back to the debugger client specified by xdebug.remote_host. This is why your older configuration using xdebug.remote_host=host.docker.internal worked; the container was pushing out an inbound connection.
Xdebug 3 flips this architecture to "client-driven." The IDE (PhpStorm) starts a listening socket on port 9001 and waits for the PHP process to connect to it. To make this work in a Docker environment, you must ensure the PHP process inside the container knows the exact IP address of your host machine where PhpStorm is running.
The configuration snippet you provided shows the correct intent:
xdebug.client_host=host.docker.internal
xdebug.client_port=9001
However, host.docker.internal is a special DNS name that resolves to the host's gateway IP. While this works in many Docker versions (like the one on Windows or macOS), it can be finicky on Linux distributions running specific kernel versions or Docker engine versions. If your Fedora 33 environment does not resolve host.docker.internal correctly, or if the container network stack drops packets destined for that specific gateway, the handshake fails immediately.
Resolving the Connection Failure
To fix this, you need to force the PHP process inside the container to connect directly to the host's loopback interface or its specific IP address, bypassing DNS resolution issues entirely.
First, identify the actual IP address of your Fedora 33 host from within the Docker network. You can do this by running a command inside the container:
docker exec <container_id> cat /etc/resolv.conf | grep nameserver
# Or check the gateway
ip route show default
However, the most robust solution is to ensure the PHP process connects via 127.0.0.1 on the host side if your IDE supports it, or explicitly set the client host to the host's gateway IP found in the container's /etc/resolv.conf.
A more modern approach for Xdebug 3 in Docker involves using the xdebug.mode=debug flag and ensuring that xdebug.start_with_request=yes is active. But the critical piece is the connection string. Instead of relying on host.docker.internal, try setting the client host to the specific IP address your Fedora machine uses on the Docker bridge network, or explicitly point it to host.docker.internal if you confirm that DNS resolution is failing inside the container logs.
If you are using PHP 8.x and Xdebug 3.1+, there is a known behavior where the default connection settings might differ slightly from earlier RC versions. Ensure you are not mixing old xdebug.remote_* directives with new xdebug.client_* ones, as they control different parts of the handshake.
Verifying the Fix
Once you have adjusted xdebug.client_host to a value that resolves correctly within your container (often requiring an explicit IP like 172.17.0.1 or the host's actual gateway IP), restart both the PHP-FPM/Apache service and your Docker containers. Then, trigger a breakpoint in PhpStorm.
If you are working on a Laravel project specifically, ensure that your .env file includes:
APP_DEBUG=1
and that the xdebug.mode is set to debug. If you encounter issues with Xdebug 3 on Fedora, consider checking if the firewalld service is blocking incoming connections on port 9001, although in this specific client-driven model, the container initiates the connection, so outbound rules on the host are usually the culprit.
By aligning the client IP settings and understanding that Xdebug 3 waits for you to connect rather than connecting for you, you can resolve the Could not connect to debugging client error and fully utilize the profiling and stepping capabilities of the new version.