Maaz Zindani

Loading the index…

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

Xdebug cannot reach the IDE: Could not connect to debugging client

ErrorXdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port)

Short answer

Xdebug found your request but could not open a connection back to the IDE. The Xdebug log shows the address it tried. Then check five settings: xdebug.mode includes debug, xdebug.client_host points at the machine running the IDE, the port matches (9003), a trigger is present, and no firewall blocks the connection.

  • Applies to Xdebug 3.4, PHP 8.3, PhpStorm, Docker
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Turn on the Xdebug log and make one request. The log names the address Xdebug tried and says why it failed. Use an absolute path the PHP user can write to.

    ; 99-xdebug.ini
    xdebug.log=/tmp/xdebug.log
    xdebug.log_level=7
  2. 2Match what you see, then jump to its fix

    1. 1The log shows no connection attempt at all for the requestStep debugging is not enabled: mode or start_with_requestFix
    2. 2Tried: localhost:9003 while PHP runs in Docker, a VM or on a remote serverclient_host points at the wrong machineFix
    3. 3Tried: host:9003 and the IDE shows no incoming connectionThe IDE listens on another port, or a firewall blocks itFix
    4. 4The attempt fails on a remote or high-latency link although host and port are rightThe connection is slow and times outFix

What does the error look like?

  • Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port)
  • Debugger never stops at a breakpoint although Xdebug is listed in phpinfo()

Cause 1 of 4

Step debugging is not enabled: mode or start_with_request

1Check

xdebug.mode defaults to develop, so debug must be added. The setting can only be set in php.ini style files, not in .htaccess, .user.ini or php_admin_value. With start_with_request=trigger a trigger such as XDEBUG_TRIGGER must be sent; with no, step debugging never starts.

php -i | grep -E 'xdebug.mode|xdebug.start_with_request'

2Fix

Add debug to the mode and start the debugger on every request while you work, or send the trigger from the browser.

; 99-xdebug.ini
xdebug.mode=develop,debug
xdebug.start_with_request=yes

3Verify

Reload PHP and request a page: the log now shows a connection attempt.

sudo systemctl reload php8.3-fpm && tail -n 20 /tmp/xdebug.log

Confirmed by xdebug.org

Did this fix it?

Cause 2 of 4

client_host points at the wrong machine

1Check

xdebug.client_host defaults to localhost. If PHP runs in another machine or a container, localhost is that container, not the IDE host. The log line shows what was tried.

grep -i 'Tried' /tmp/xdebug.log

2Fix

Point client_host at the machine that runs the IDE. On Linux, xdebug://gateway and xdebug://nameserver are also accepted values; nameserver does not work on musl-based images such as Alpine.

; 99-xdebug.ini
xdebug.client_host=192.168.1.20
; or on Linux
; xdebug.client_host=xdebug://gateway

3Verify

The next log line shows the new host, with Connected or a different failure.

tail -n 20 /tmp/xdebug.log

Confirmed by xdebug.org

Did this fix it?

Cause 3 of 4

The IDE listens on another port, or a firewall blocks it

1Check

client_port defaults to 9003 and must match the port the IDE listens on. The PHP host must be able to reach the IDE's IP and port, and nothing may block the incoming connection.

php -i | grep xdebug.client_port

2Fix

Set the IDE's debug port to 9003 (the default for Xdebug 3) or change xdebug.client_port to the IDE's value, and allow the port through the firewall on the IDE machine.

; 99-xdebug.ini
xdebug.client_port=9003

3Verify

Start listening in the IDE and repeat the request; the IDE shows the incoming connection.

tail -n 20 /tmp/xdebug.log

Confirmed by xdebug.org

Did this fix it?

Cause 4 of 4

The connection is slow and times out

1Check

xdebug.connect_timeout_ms defaults to 200. A slow network or firewall can need more, but a higher value makes requests seem to hang when the IDE is not listening.

php -i | grep xdebug.connect_timeout_ms

2Fix

Raise the timeout a little for that environment only.

; 99-xdebug.ini
xdebug.connect_timeout_ms=2000

3Verify

Repeat the request and read the log.

tail -n 20 /tmp/xdebug.log

Confirmed by xdebug.org

Did this fix it?

How do I stop it coming back?

  • Keep the Xdebug settings in one 99-xdebug.ini per environment and switch the log on only while debugging.
  • Run Xdebug only in development images. Step debugging on a public server is a security risk.
  • On systemd hosts PHP-FPM may use a private tmp directory; look for the log under that directory if /tmp/xdebug.log does not appear.

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

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

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