Diagnosing PhpStorm Xdebug Breakpoints That Are Not Hit

Problem: Breakpoints Ignored in PhpStorm

When you launch a debugging session in PhpStorm, the script executes to completion without stopping at any breakpoint you have set. This guide provides a systematic diagnosis to uncover why Xdebug is not communicating with the IDE and shows how to restore breakpoint hits.

Recognizable Condition

Breakpoints appear as red circles in the gutter, but during a debug run the IDE console shows "Connected to Xdebug" (or similar) and the request finishes without pausing.

Cause / Diagnostic Table

Possible Cause	Quick Check
Xdebug extension not loaded	Run php -i | grep -i xdebug or view phpinfo() in a browser
Version mismatch (Xdebug 2 with PHP 8+)	Compare PHP version from php -v with Xdebug version shown in phpinfo()
Port mismatch between Xdebug and PhpStorm DBGp settings	Check xdebug.client_port in php.ini vs. PhpStorm Settings → PHP → Debug → DBGp proxy port
External connections disabled in PhpStorm	Verify "Can accept external connections" is enabled under Settings → PHP → Debug
Path mapping incorrect (local ↔ remote)	Open Settings → PHP → Servers and compare the absolute path of the project with the server path mapping
Firewall blocking the debug port	Attempt to telnet to the host on the configured port; connection refused or timeout indicates a block

Ordered Checks

1. Verify Xdebug is loaded
   1. Open a terminal and run:
      php -i | grep -i xdebug
   2. If no output, create a file info.php with <?php phpinfo(); ?>, request it via your web server, and look for the Xdebug section.

   Where to run: Terminal with user that can execute the PHP CLI (usually your development user). No special privileges needed.

   Expected check: You should see a line like xdebug followed by version information.

   Risk: None.

2. Confirm Xdebug version matches PHP version
   1. Check PHP version: php -v (e.g., PHP 8.2.4).
   2. Check Xdebug version from phpinfo() or the CLI output above (e.g., Xdebug 3.2.2).
   3. Use the compatibility matrix: Xdebug 3.x for PHP 8.0+, Xdebug 2.x for PHP 7.x and earlier.

   Where to run: Same terminal.

   Expected check: Version numbers fall within the compatible range.

   Risk: None.

3. Match Xdebug client port with PhpStorm DBGp port
   1. Locate xdebug.client_port in your php.ini (commonly 9003).
   2. In PhpStorm: Settings → PHP → Debug → DBGp proxy. Ensure the port matches the value from php.ini.
   3. Ensure "Can accept external connections" is checked.

   Where to run: Edit php.ini (requires file system write permission, often root or sudo on Linux/macOS, administrator on Windows). PhpStorm settings need no special rights.

   Expected check: Both values identical (e.g., 9003).

   Risk: Changing the port requires restarting the web server and PhpStorm for the new setting to take effect.

4. Validate path mapping
   1. Open Settings → PHP → Servers.
   2. Select the server used for debugging (often named localhost or a custom name).
   3. Under "Path mappings", ensure the "Absolute path on the server" corresponds to the actual directory containing your source code, and the "File/Directory" column points to your local project root.

   Where to run: PhpStorm UI.

   Expected check: The mapping shows the same project folder on both sides (e.g., Server: /var/www/html/project ↔ Local: /Users/me/project).

   Risk: Incorrect mapping can cause Xdebug to send breakpoints for files it cannot locate, leading to silent ignores.

5. Check firewall or security software
   1. Identify the debug port (from step 3).
   2. On Linux: sudo iptables -L | grep or ss -tlnp | grep .
   3. On Windows: Open Windows Defender Firewall → Advanced Settings → Inbound Rules and look for a rule allowing the port.
   4. On macOS: Use sudo pfctl -s rules | grep or check the built‑in firewall preferences.

   Where to run: Terminal with administrator/root privileges.

   Expected check: The port is listed as listening (state LISTEN) and not blocked by a rule.

   Risk: Adding a rule exposes the port to the network; restrict to localhost or your development subnet if possible.

Fixes Tied to Findings

• Xdebug not loaded: Install via PECL (pecl install xdebug) or your OS package manager, then add zend_extension=xdebug.so (Linux/macOS) or zend_extension="C:\\php\\ext\\php_xdebug.dll" (Windows) to php.ini and restart the web server.
• Version mismatch: Upgrade or downgrade Xdebug to a compatible release (e.g., pecl install xdebug-3.2.2 for PHP 8.2).
• Port mismatch: Edit xdebug.client_port in php.ini to match PhpStorm’s DBGp port (or vice‑versa), then restart the web server and PhpStorm.
• External connections disabled: Enable "Can accept external connections" in PhpStorm Settings → PHP → Debug and click Apply.
• Path mapping incorrect: Adjust the "Absolute path on the server" field to match the real path of the project on the server (often visible via pwd in a shell on the server) and ensure the local side points to your project directory.
• Firewall blocking: Create an inbound rule allowing TCP traffic on the debug port (e.g., 9003) for the interface used by the web server (usually localhost or the server’s IP).

Practical Verification After Each Fix

1. Create a simple test script test.php containing:

   <?php
   xdebug_break();
   echo "Hello Xdebug\n";
   ?>

2. Request the script via your web server (e.g., http://localhost/test.php) while the PhpStorm debugger is listening.
3. Observe the PhpStorm debugger pane: execution should pause at the line with xdebug_break() and the Variables view should be populated.
4. If the breakpoint is hit, the configuration is working; otherwise, proceed to the next check in the ordered list.

Escalation Criteria

If you have completed all six ordered checks, verified that Xdebug is loaded, version‑compatible, ports match, external connections are allowed, path mapping is correct, and the firewall permits the debug port, yet breakpoints are still ignored:

• Enable IDE diagnostic logging: Help → Diagnostic Tools → Debug Log Settings → set "Debug" level for "com.intellij.xdebugger" and reproduce the issue.
• Enable Xdebug logging by adding to php.ini:

  xdebug.log=/tmp/xdebug.log
  xdebug.log_level=0

• Collect the following information and contact JetBrains support (or post to the PhpStorm forum):
  • PHP version (php -v)
  • Xdebug version (from phpinfo())
  • Operating system and version
  • Relevant php.ini snippets (xdebug section)
  • PhpStorm Debugger settings screenshot (ports, external connections)
  • Path mapping table from Settings → PHP → Servers
  • IDE log (idea.log) and Xdebug log (/tmp/xdebug.log)

Limitations

• Xdebug 2.x is not compatible with PHP 8.0+; even if the extension loads, breakpoints will be ignored.
• Path mapping is only relevant when debugging via a web server or remote interpreter; CLI debugging uses the local file system directly.
• Some security extensions (e.g., Suhosin, SELinux) may block the debug connection even if the firewall allows it; consult their logs if the issue persists.

By following the ordered checks and applying the fixes that correspond to each finding, you can systematically restore breakpoint functionality in PhpStorm.