Xdebug cannot reach the IDE: Could not connect to debugging client
Xdebug: [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.
Fix it fast
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=72Match what you see, then jump to its fix
- 1
The log shows no connection attempt at all for the requestStep debugging is not enabled: mode or start_with_requestFix - 2
Tried: localhost:9003 while PHP runs in Docker, a VM or on a remote serverclient_host points at the wrong machineFix - 3
Tried: host:9003 and the IDE shows no incoming connectionThe IDE listens on another port, or a firewall blocks itFix - 4
The attempt fails on a remote or high-latency link although host and port are rightThe connection is slow and times outFix
- 1
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=yes3Verify
Reload PHP and request a page: the log now shows a connection attempt.
sudo systemctl reload php8.3-fpm && tail -n 20 /tmp/xdebug.logConfirmed by xdebug.org
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.log2Fix
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://gateway3Verify
The next log line shows the new host, with Connected or a different failure.
tail -n 20 /tmp/xdebug.logConfirmed by xdebug.org
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_port2Fix
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=90033Verify
Start listening in the IDE and repeat the request; the IDE shows the incoming connection.
tail -n 20 /tmp/xdebug.logConfirmed by xdebug.org
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_ms2Fix
Raise the timeout a little for that environment only.
; 99-xdebug.ini
xdebug.connect_timeout_ms=20003Verify
Repeat the request and read the log.
tail -n 20 /tmp/xdebug.logConfirmed by xdebug.org
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- Spotless LaundryAn on-demand laundry app: Flutter on a Laravel back end, with Firebase for live updates.
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 fixBack end
docker build stops at RUN composer install with exit code 1
Allowed memory size of ... bytes exhausted
Exit code 1 only says the RUN step failed.
4 causes, each with a fixBack end
memory_limit does not change inside a PHP Docker container
memory_limit is still 128M after editing php.ini in the container
Your setting is being read from the wrong place or overridden.
4 causes, each with a fixBack end
php artisan serve starts but the app is not reachable, or the .env is ignored
Server stops right after start with a non-zero exit code when --port is given and the port is busy
php artisan serve listens on 127.0.0.1 port 8000 by default.
4 causes, each with a fixBack end
Guzzle or Http::get fails with cURL error 6 in Laravel
Illuminate\Http\Client\ConnectionException: cURL error 6: Could not resolve host
cURL error 6 means the machine running PHP could not turn the host name in the URL into an IP address.
3 causes, each with a fixBack end
Laravel cannot find the database host: getaddrinfo failed
SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo for mysql failed
The message means PHP could not turn DB_HOST into an IP address.
3 causes, each with a fix