Try or ByeTry or Bye

PhpStorm Xdebug Not Connecting / Breakpoints Not Hit

Share
Workaround available Windows, macOS, Linux, Docker Updated November 14, 2026Based on 5 user reportsHow we research

Quick answer

The usual causes are a wrong client_host or port, missing path mappings, or Xdebug not in debug mode. Check port 9003, host.docker.internal and map the whole project root.

Most likely fix: Check Xdebug settings

How to fix it

Try these in order — the most common fix is first.

  1. 1. Check Xdebug settings

    1. Set xdebug.mode=debug and xdebug.start_with_request=yes (or trigger it)
    2. Set xdebug.client_port=9003 and match it under Settings | PHP | Debug
    3. Restart PHP or the container
    Did this fix it?

  2. 2. Docker and Sail: reach the host

    1. Set xdebug.client_host=host.docker.internal
    2. On Linux add an extra_hosts entry mapping host.docker.internal to host-gateway
    3. For Laravel Sail set XDEBUG_MODE and XDEBUG_CONFIG explicitly in docker-compose.yml
    Did this fix it?

  3. 3. Fix path mappings

    1. Map the project root to the path inside the container (often /var/www/html)
    2. Do not map only a subfolder
    Did this fix it?

  4. 4. Test the breakpoint

    1. Place it on a simple one-line assignment
    2. Enable Resolve breakpoint if it is not available on the current line in Debug settings
    Did this fix it?

Symptoms

The listener is on but PhpStorm never stops at breakpoints, or it shows "Waiting for incoming connection with ide key".

Why it happens

  • Xdebug 3 uses port 9003 but the IDE or php.ini still expects 9000
  • xdebug.client_host cannot reach the IDE from Docker or a VM
  • Path mappings missing or only partial (for example vendor not mapped)
  • Breakpoint on a line with no executable code
  • xdebug.mode does not include debug

This guide also covers

  • phpstorm xdebug not working
  • phpstorm breakpoint not hit
  • phpstorm xdebug docker
  • phpstorm waiting for incoming connection

Still not working?

If PhpStorm keeps failing, you're not alone. See every PhpStorm problem users report or the alternatives people switch to.

Have an app idea? Our small team builds any software: web and mobile apps, games, desktop, AI tools. Price agreed together.

Talk to us
Fixed it? Share this guide

The same problem in other apps

All not loading, error messages & connection guides →

Other PhpStorm errors

All 10 PhpStorm errors and fixes →