Diagnosing Xdebug Connection Failures in PhpStorm

Recognisable Condition

When you start a debugging session in PhpStorm the IDE shows "Waiting for Xdebug connection…" and breakpoints are never hit. The session never begins, or it ends immediately with a timeout. This is the most common symptom that the IDE cannot establish a DBGp connection to the Xdebug engine running on your web server or PHP CLI.

Common Causes & Diagnostic Table

Cause	What to Check	Expected Result
Xdebug not installed or disabled	Run php -i | grep Xdebug on the command line used by your web server (or phpinfo() in a browser)	Output shows an Xdebug section with a version number
Wrong Xdebug configuration keys (Xdebug 2 vs 3)	Check xdebug.mode, xdebug.client_host, xdebug.client_port (Xdebug 3) or xdebug.remote_enable, xdebug.remote_host, xdebug.remote_port (Xdebug 2)	Values match the PhpStorm settings
Port mismatch	Verify xdebug.client_port (default 9003) and that PhpStorm’s DBGp proxy is listening on the same port	Both sides agree on the same port number
Firewall or SELinux blocking inbound traffic	Check that the host allows TCP connections to the debugging port (9003 or 9000)	Port is reachable from the IDE’s machine
Incorrect path mapping	In Settings > PHP > Servers, ensure the Absolute path on server matches the project root on the IDE	IDE can map breakpoints to the correct files
PhpStorm listening on the wrong interface	Check the DBGp proxy host is set to localhost or the IP that Xdebug uses to connect back	IDE accepts connections from the server

Ordered Diagnostic Checklist

1. Confirm Xdebug is loaded

   Run on the server (or the web‑server user):

   php -i | grep -i xdebug
   

   If nothing appears, install or enable the extension. For Debian/Ubuntu:

   sudo apt-get install php-xdebug
   sudo phpenmod xdebug
   sudo systemctl restart apache2
   

2. Check the Xdebug mode and host/port

   In php.ini or a dedicated xdebug.ini file, ensure:

   # Xdebug 3 syntax
   xdebug.mode=debug
   xdebug.start_with_request=yes
   xdebug.client_host=127.0.0.1
   xdebug.client_port=9003
   

   For Xdebug 2 use the legacy keys:

   xdebug.remote_enable=1
   xdebug.remote_host=127.0.0.1
   xdebug.remote_port=9000
   

   Restart the web server after changes.
3. Validate PhpStorm DBGp proxy

   Open Settings > PHP > Debug in PhpStorm. The DBGp Proxy section should show Host: localhost and Port: 9003 (or 9000 if you are using Xdebug 2). If you changed the port in php.ini, update it here.

4. Verify firewall/SELinux rules

   On Linux, run:

   sudo ufw allow 9003/tcp
   

   On Windows, add an inbound rule for TCP port 9003. If SELinux is enforcing, add a policy: semanage port -a -t http_port_t -p tcp 9003.
5. Check path mapping

   In Settings > PHP > Servers, add a server that matches the URL you are debugging. Tick Use path mappings and set the Absolute path on server to the real filesystem location (e.g., /var/www/html). The IDE will then translate file paths from the server to the local project.

6. Test the connection manually

   Create a PHP file with phpinfo(); and access it via the browser. In the Xdebug section you should see mode=debug and the client host/port values. If they differ, adjust the ini file.

Fixes Tied to Findings

• Xdebug not loaded – Install the extension, enable it, and restart the web server.
• Wrong config keys – Replace legacy remote_ keys with the new xdebug.mode syntax (or vice‑versa if you must stay on Xdebug 2).
• Port mismatch – Align xdebug.client_port and PhpStorm’s DBGp port. Remember Xdebug 3 defaults to 9003, while older setups used 9000.
• Firewall blocking – Add an allow rule for the debugging port on the host machine.
• Path mapping error – Update the server mapping in PhpStorm so that the IDE can resolve file paths correctly.
• IDE listening on wrong interface – Make sure the DBGp proxy host is localhost or the IP that Xdebug connects back to.

Escalation Criteria

If after applying the above fixes the IDE still shows Waiting for Xdebug connection or breakpoints are never hit, collect the following logs and contact JetBrains support:

• Xdebug log – Enable it by adding xdebug.log=/tmp/xdebug.log to php.ini and review the file for connection attempts.
• PhpStorm IDE log – Help > Show Log in Explorer/Finder and look for DBGp errors.
• Environment details – PHP version, Xdebug version, PhpStorm version, OS, and whether you are debugging via a web server or CLI.
• Network trace – On the host, run sudo tcpdump -i any port 9003 (or 9000) to verify that a connection attempt from the IDE is reaching the server.

Limitations & Practical Checks

• PhpStorm versions before 2020.2 do not support Xdebug 3. Upgrade if you are using the new syntax.
• Xdebug 3 changed the default port; if you have legacy configuration files, double‑check the port values.
• On shared hosts, you may not have permission to edit php.ini; in that case use .htaccess or php_value directives if supported.
• After any change, always clear the IDE’s debugger cache: File > Invalidate Caches / Restart.

Concrete Example

Assume a Docker container running php:8.1-apache where the web root is /var/www/html. The host machine runs PhpStorm on Windows.

1. In /usr/local/etc/php/conf.d/xdebug.ini (inside the container):

   zend_extension=xdebug
   xdebug.mode=debug
   xdebug.start_with_request=yes
   xdebug.client_host=host.docker.internal
   xdebug.client_port=9003
   

2. Restart Apache inside the container: docker exec -it myapp apachectl restart.
3. In PhpStorm, add a server named myapp.local with URL http://myapp.local, set the absolute path to C:\projects\myapp, and ensure the DBGp port is 9003.
4. Start a debug session. The console should show Connected to Xdebug (client 127.0.0.1:9003) and breakpoints will pause execution.

Conclusion

By following the ordered checklist and aligning both the Xdebug configuration and PhpStorm’s debugger settings, most connection issues can be resolved quickly. If the problem persists, the logs and network traces collected above provide a clear path for JetBrains support to diagnose deeper networking or compatibility problems.