Xdebug starts a session, but PhpStorm ignores my breakpoints
The debugger connects but execution never stops at my breakpointsShort answer
If the IDE shows a connection but PHP runs straight through, the usual cause is a mismatch between the files Xdebug reports and the files you opened. Turn on xdebug.log first. Then check the server path mappings, whether the breakpoint sits on a line with code, and whether IDE and Xdebug use the same port.
Fix it fast
1Find out which cause you have
Write Xdebug's own conversation with the IDE to a log, then run one debug request. The log shows what was exchanged. Switch it off again afterwards because the file never rotates.
; php.ini or a conf.d file xdebug.log="/tmp/xdebug.log"2Match what you see, then jump to its fix
- 1
The session starts, your own breakpoints are skippedPath mappings do not match the files on the serverFix - 2
The breakpoint moves to a nearby line, or is shown as disabled in the breakpoint listThe breakpoint is on a line without executable code, or is disabledFix - 3
The port number in the IDE differs from xdebug.client_portThe IDE and Xdebug use different portsFix - 4
php --version prints a warning, such as a module that failed to load, before the versionPHP prints a warning before its own version lineFix
- 1
What does the error look like?
The debugger connects but execution never stops at my breakpointsA breakpoint jumps to a different line when the session starts
Cause 1 of 4
Path mappings do not match the files on the server
1Check
In PhpStorm open Settings, then PHP, then Servers. Compare the server's file path with the project path on your computer. If the web server runs the same files as your project with no symlinks in between, mappings are not needed.
# PhpStorm: Settings > PHP > Servers
# Run on the server to see the real path of the script:
php -r 'echo realpath("index.php"), PHP_EOL;'2Fix
If no symlinks are involved, clear the option to use path mappings. Otherwise map each project folder to the matching absolute folder on the server.
# Example mapping
# Project: /Users/me/project/public -> Server: /var/www/html/public3Verify
Start a debug session again and confirm the breakpoint turns into a checked circle and execution stops there.
# Run > Start Listening for PHP Debug Connections, then reload the pageConfirmed by jetbrains.com
Cause 2 of 4
The breakpoint is on a line without executable code, or is disabled
1Check
Open the breakpoint list (Run, then View Breakpoints) and look for unchecked entries. Xdebug moves a breakpoint from a line that holds no code to a nearby one.
# PhpStorm: Run > View Breakpoints (Ctrl+Shift+F8)2Fix
Enable the breakpoint, and put it on a line that does something, such as a statement or a function call. Comment lines, braces and blank lines hold no code.
// not on this line
$total = $price * $qty; // put it here3Verify
Run the request again and check the IDE stops on that statement.
# Run > Start Listening for PHP Debug ConnectionsConfirmed by jetbrains.com
Cause 3 of 4
The IDE and Xdebug use different ports
1Check
Find the port the IDE listens on in Settings, PHP, Debug, and compare it with xdebug.client_port in the loaded php.ini.
php --ini
php -i | grep xdebug.client_port2Fix
Make both numbers the same; 9003 below is an example.
; php.ini
xdebug.client_port=90033Verify
Restart PHP or the web server, run one debug request and read the log.
tail -n 20 /tmp/xdebug.logConfirmed by jetbrains.com
Cause 4 of 4
PHP prints a warning before its own version line
1Check
Warnings printed at startup can disturb the debug session. Run the command and read the first lines.
php --version2Fix
Fix whatever the warning names, for example a wrong path to the Xdebug extension, until the first line is the PHP version.
php --ini
# edit the file that holds the failing line3Verify
php --version prints only version information, and a new debug request stops on the breakpoint.
php --versionConfirmed by jetbrains.com
How do I stop it coming back?
- Keep one php.ini change per step and check php --ini so you know which file PHP actually reads.
- Turn xdebug.log off after debugging, since the file does not roll over.
- Rename files from the IDE or with mv; a case-only rename in Finder can break file lookups on macOS.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
Xdebug cannot reach the IDE: Could not connect to debugging client
Debugger never stops at a breakpoint although Xdebug is listed in phpinfo()
Xdebug found your request but could not open a connection back to the IDE.
4 causes, each with a fixBack end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack end
Apache returns 403 when a URL contains %3F
a request like /page%3Fname=test is refused while /page?name=test works
Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.
2 causes, each with a fixBack end
Apache returns 500 with Premature end of script headers
500 Internal Server Error
Apache ran your script, but the script printed no valid HTTP header before its output.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fix