Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Xdebug starts a session, but PhpStorm ignores my breakpoints

ErrorThe debugger connects but execution never stops at my breakpoints

Short 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.

  • Applies to PhpStorm 2024.3, Xdebug 3, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1The session starts, your own breakpoints are skippedPath mappings do not match the files on the serverFix
    2. 2The 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. 3The port number in the IDE differs from xdebug.client_portThe IDE and Xdebug use different portsFix
    4. 4php --version prints a warning, such as a module that failed to load, before the versionPHP prints a warning before its own version lineFix

What does the error look like?

  • The debugger connects but execution never stops at my breakpoints
  • A 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/public

3Verify

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 page

Confirmed by jetbrains.com

Did this fix it?

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 here

3Verify

Run the request again and check the IDE stops on that statement.

# Run > Start Listening for PHP Debug Connections

Confirmed by jetbrains.com

Did this fix it?

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_port

2Fix

Make both numbers the same; 9003 below is an example.

; php.ini
xdebug.client_port=9003

3Verify

Restart PHP or the web server, run one debug request and read the log.

tail -n 20 /tmp/xdebug.log

Confirmed by jetbrains.com

Did this fix it?

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 --version

2Fix

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 line

3Verify

php --version prints only version information, and a new debug request stops on the breakpoint.

php --version

Confirmed by jetbrains.com

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.