Debug your XDebug: Advanced Troubleshooting part 1 — Network Issues

XDebug is unarguably an essential tool for developers who work with PHP. Although some of us debug their code using logging and debug output only, XDebug allows to get much richer and deeper insight into PHP application internals and as a result helps to find bugs easier and faster.

However sometimes it is not so easy to set up XDebug in order to make it work with your favorite IDE. There are official XDebug setup guides for many popular IDE including PHPStorm, NetBeans, Eclipse and VSCode, but sometimes XDebug is set up in full accordance with documentation but doesn’t work and it is hard to find why. In the typical case IDE when trying to start debugging listens to connection from XDebug and does not receive it. Especially often this happens with applications work under Docker-powered PHP.

If it is your case it’s time to get more understanding of XDebug internals in order to find the problem. First let’s get acquainted with how XDebug talks to your IDE. For communication it uses a simple TCP-based text network protocol called DBGp that with default settings works on TCP port 9000 though can be set up to use another port. Using DBGp XDebug informs IDE (or another tool that understands DBGp) that debugging session has started and IDE in turn can control debug process with commands that it sends to XDebug.

When IDE listens to connections from XDebug but does not receive them it happens mainly because of two reasons:

1. XDebug tries to connect IDE host but cannot reach it
2. XDebug does not try to connect IDE host at all

The first point is definitely a network problem, the second problem shows an issue with XDebug itself which is likely wrong XDebug settings. But until we sort out network issues we cannot clearly see that XDebug does not try to connect IDE host. However if IDE and XDebug both work on your local machine then network communication is very likely not the issue.

The typical plan for solving XDebug network issues is following:

1. Ensure that XDebug settings are correct
2. Check if XDebug network host can communicate network IDE host
3. Ensure that IDE can receive data from Xdebug

To debug network connection it you will need some network testing tool and some tool that can show incoming XDebug connections. For network testing I use ping and telnet and for XDebug incoming connection debugging I would recommend dbgpClient — a command line XDebug client which is more suitable is our purposes than a typical IDE because it shows all incoming XDebug connections and data which is more helpful than a typical IDE’s showing “Listening to PHP debug connection” but not receiving it. Now we are ready to fight the problem, lets the battle begin.

1. Ensure that XDebug settings are correct

The very first step — to ensure that XDebug settings are correct. From Xdebug host execute:

$ php — info | grep xdebug

Which should output something like:

/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini,
xdebug.auto_trace => This setting has been changed, see the upgrading guide at https://xdebug.org/docs/upgrade_guide#changed-"xdebug.auto_trace" => This setting has been changed, see the upgrading guide at https://xdebug.org/docs/upgrade_guide#changed-"xdebug.auto_trace"
xdebug.cli_color => 0 => 0
xdebug.client_discovery_header => no value => no value
xdebug.client_host => <your_IDE_host_IP> => <your_IDE_host_IP>
xdebug.client_port => 9000 => 9000
…

If the output does not contains these settings then XDebug is not installed or is not set up correctly to work with your PHP-interpreter, check its settings according the manual.

Now ensure that <your_IDE_host_IP> is a valid IP of the host where you work with your IDE and client_port parameter shows the port that is set up in your IDE to work with XDebug. For example in my case Xdebug works in Docker container with IP 172.18.0.6 with port 9000 and my IDE works on my my local workstation which has Docker network IP 172.18.0.1. By the way local host IP in Docker network you can find by looking it up in “Gateway” field in output of command:

$ docker network inspect <your_docker_network_name>
[{
“Name”: “<your_docker_network_name>”,
…
“IPAM”: {
“Driver”: “default”,
“Options”: null,
“Config”: [{
“Subnet”: “172.18.0.0/16”,
“Gateway”: “172.18.0.1”
}]
},
…

2. Check if XDebug network host can communicate network IDE host

When we know that XDebug settings are correct it’s time to check if XDebug can communicate the network IDE host. Of course if IDE and XDebug both work on the same machine you can skip this.

From your XDebug host execute ping <your_IDE_host_IP>, here is its output on my machine:

$ ping 172.18.0.1
PING 172.18.0.1 (172.18.0.1): 56 data bytes
64 bytes from 172.18.0.1: seq=0 ttl=64 time=0.162 ms
64 bytes from 172.18.0.1: seq=1 ttl=64 time=0.142 ms
…

As we can see, IDE host is reachable from the XDebug host. If not check your IDE host IP and adjust XDebug host networks settings in order to make IDE host reachable.

3. Ensure that IDE can receive data from Xdebug

The next step is to ensure that IDE can receive commands from Xdebug. Start dbgpClient on IDE host:

$ ./dbgpClient
Xdebug Simple DBGp client (0.4)
Copyright 2019–2020 by Derick Rethans
In dumb client mode
Waiting for debug server to connect on port 9000.

and use telnet to simulate sending commands from Xdebug host to port used by DBGp (9000 with XDebug default settings).

$ telnet 172.18.0.1 9000
Connected to 172.18.0.1

now on XDebug host we should get:

Waiting for debug server to connect on port 9000.
Connect from 172.18.0.6:45410

Here we see that XDebug can send data to IDE and IDE can receive them.

If your result is different then the problem cause can be somewhere in network between XDebug and IDE’s network hosts.

At this moment we know that network issues do not prevent XDebug from working. Try to start debugging PHP-code with you IDE, if it works then the problem was in network communication. Sometimes however network issues can be even more complicated like this question on Stackoverflow where XDebug won’t work because of some smart firewall in corporate provider network on a way between . Then you should communicate the administrator of that firewall in order to adjust its setting to allow XDebug to communicate with IDE.

If network issues are sorted out and XDebug still doesn’t work then it’s time to debug how XDebug works with PHP interpreter which will be described in the Part 2 of the article which will be published soon.