Diagnosing PhpStorm 2024.x Xdebug 3 Connection Failures on Localhost

Recognizable Condition

PhpStorm displays "Waiting for incoming connection with ide key 'PHPSTORM'" indefinitely. No breakpoint is hit, the Debug tool window stays empty, and the browser shows the page loading without pausing.

Quick Cause & Diagnostic Table

Ordered Diagnostic Checks

1. Verify active Xdebug settings
   Run php -v and php -i | grep -E 'xdebug\.(mode|client_port|idekey|client_host)'. Confirm xdebug.mode=debug, xdebug.client_port=9003, xdebug.idekey=PHPSTORM, and xdebug.client_host=127.0.0.1 (or host.docker.internal for Docker).
2. Start listening in PhpStorm
   Run → Start Listening for PHP Debug Connections (phone icon). The status bar should show "Listening for debug connections on port 9003".
3. Validate Server configuration
   Settings → PHP → Servers. Ensure a server entry exists for localhost (or your virtual host) with port 80/443. Add Path Mapping: absolute path on server (e.g., /var/www/html) mapped to your local project directory.
4. Confirm browser helper idekey
   Click the Xdebug helper extension (Chrome/Firefox). Set IDE Key to "PHPSTORM" (or match your xdebug.idekey). Toggle off/on after changes.
5. Test CLI debug
   Run php -dxdebug.start_with_request=yes -dxdebug.mode=debug script.php. PhpStorm should break at the first line if listening.
6. Check port binding and firewall
   Run ss -ltnp | grep 9003 on Linux/macOS or netstat -an | findstr 9003 on Windows. Ensure PhpStorm (java) holds the port. If missing, allow 9003/tcp in firewall (sudo ufw allow 9003/tcp or Windows Defender rule).

Fixes Tied to Findings

Closed Port / Firewall

Linux: sudo ufw allow 9003/tcp or firewall-cmd --add-port=9003/tcp --permanent. Windows: New Inbound Rule → Port → TCP 9003 → Allow. SELinux: setsebool -P httpd_can_network_connect 1 if Apache/PHP-FPM runs confined.

IDE Key Mismatch

Edit xdebug.idekey=PHPSTORM in the php.ini reported by php --ini. Restart PHP-FPM/Apache. Reset browser extension to same key.

Missing Path Mapping

In Settings → PHP → Servers, add mapping: /var/www/html/project → C:\Users\dev\project (or your local path). Use absolute paths on both sides.

Wrong php.ini Edited

Run php --ini. Note "Loaded Configuration File". Edit that file. For FPM, also check /etc/php/8.3/fpm/php.ini (adjust version). Restart service: sudo systemctl restart php8.3-fpm.

Multiple PHP Versions

Settings → PHP → CLI Interpreter → point to the binary used by your web server (e.g., /usr/bin/php8.3). Click "..." → Show phpinfo to verify Xdebug section matches web SAPI.

Escalation Criteria

Contact JetBrains Support when:

• All checks pass but a clean project still fails.
• Help → Collect Logs shows XDebugConnectionManager exceptions.
• Xdebug log (xdebug.log=/tmp/xdebug.log with xdebug.log_level=7) shows "Cannot connect to client" despite correct port.
• Issue reproduces on a second machine with identical config.

Verification Steps

1. Run php -v and confirm Xdebug 3.x loaded.
2. Run php -i | grep -E 'xdebug\.(mode|client_port|idekey|client_host)' and verify values.
3. Enable xdebug.log=/tmp/xdebug.log and xdebug.log_level=7 in php.ini, restart PHP, tail log during debug attempt.
4. Use nc -l 9003 or socat TCP-LISTEN:9003,fork - to see raw DBGp packets from Xdebug.
5. In PhpStorm, confirm Debug tool window shows "Connected" and stack frames when breakpoint hits.
6. Help → About → verify PhpStorm version ≥ 2024.1 (native Xdebug 3 support).

Limitations & Notes

• Xdebug 2 settings (xdebug.remote_*) are ignored in Xdebug 3; only xdebug.client_* and xdebug.mode apply.
• PhpStorm's Web Server Debug Validation (Run → Web Server Debug Validation) checks CLI SAPI, not FPM/Apache module. A passing validation does not guarantee web debugging works.
• Docker: set xdebug.client_host=host.docker.internal. WSL2: use WSL host IP (ip route | awk '/default/ {print $3}') and forward port 9003.
• OpCache/JIT caches php.ini values; always restart PHP-FPM/Apache after changes.
• Browser debug extensions cache idekey; toggle or reinstall after changes.