Be part of JetBrains PHPverse 2026 on June 9 – a free online event bringing PHP devs worldwide together.

SmyGeb05's avatar

xDebug and sail php artisan:[anything]

If I issue any artisan command in the terminal, I always get the following response.

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

Often the the command 'works' or functions, but I have found that sometimes the artisan commands do not work. e.g. I was working on a project recently, and [sail php artisan make:migration] and [sail php artisan make:model -m] did not function. In the second case, artisan successfully made the model, but the migration failed. I am wondering if the combination of docker / sail is causing this.

I just did a clean install using the Laravel documentation and docker. I then added Jetstream and telescope running the migrations. when I issue the [sail php artisan route:list] the computer successfully lists all the routes, however I get the debug error or warning before and after the routes are listed.

sail php artisan route:list
Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (fallback through xdebug.client_host/xdebug.client_port) :-(
+--------+----------+----------------------------------------------------------+---------------------------------+---------------------------------------------------------------------------------+-----------------------------------------------------------+
| Domain | Method   | URI                                                      | Name                            | Action                                                                          | Middleware                                                |
+--------+----------+----------------------------------------------------------+---------------------------------+---------------------------------------------------------------------------------+-----------------------------------------------------------+
|        | GET|HEAD | /                                                        |                                 | Closure                                                                         | web                                                       |
.......
........
.......
|        | POST     | user/two-factor-recovery-codes                           |                                 | Laravel\Fortify\Http\Controllers\RecoveryCodeController@store                   | web                                                       |
|        |          |                                                          |                                 |                                                                                 | App\Http\Middleware\Authenticate                          |
|        |          |                                                          |                                 |                                                                                 | Illuminate\Auth\Middleware\RequirePassword                |
+--------+----------+----------------------------------------------------------+---------------------------------+---------------------------------------------------------------------------------+-----------------------------------------------------------+
Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (fallback through xdebug.client_host/xdebug.client_port) :-(
Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (fallback through xdebug.client_host/xdebug.client_port) :-(

Any thoughts on how I can get [xdebug] and artisan to play nicely together.

My ultimate goal is to be able to use [xdebug] and PHP-Storm.

Thanks for any help and / or suggestions in advance

R B Davis

0 likes
9 replies
piljac1's avatar

What are you Xdebug settings (in your php.ini or any other .ini file you used to define those)?

SmyGeb05's avatar

Hi, I am using the php.ini that came packaged with the Laravel / Docker installer (installation described here: https://laravel.com/docs/8.x/installation#getting-started-on-macos.

The following ini is listed as being loaded: '/etc/php/8.0/cli/conf.d/20-xdebug.ini,'

Also, perhaps relevant is:

'This program makes use of the Zend Scripting Language Engine: Zend Engine v4.0.2, Copyright (c) Zend Technologies with Zend OPcache v8.0.2, Copyright (c), by Zend Technologies with Xdebug v3.0.2, Copyright (c) 2002-2021, by Derick Rethans'

I am using Docker Desktop. The installation, according to phpinfo(), installed debug 3.0.2. The XDebug section starts with a list of features, most of which are 'disabled'.

Enabled => Step Debugger

Disabled => Development Aids, Coverage, GC Stats, Profiler, Tracing

The IDE Key has no value. Perhaps I need to provide that - I am using PHP Storm.

The debug.client_host is set to localhost, which I believe is correct, as that is the host that docker works with. port I set to 9003 as the response from artisan above suggests.

There are approximately 75 Directive Settings, Local and Master Values, 5 of which are labeled 'setting removed in xdebug3', 21 of which are labeled 'setting renamed in xDebug 3'.

Thanks for your comments in advance.

rbd

danielr192's avatar

When executing artisan commands in Sail, I believe the convention is sail artisan route:list instead of sail php artisan route:list Not sure if that makes any difference, but thought I'd throw that out there.

SmyGeb05's avatar

thx for the reply. 'sail php artisan .....' and 'sail artisan ....' are both returning the Xdebug warning for me.

piljac1's avatar

You can check out the following config. However, I wouldn't define "xdebug.start_with_request = yes" as it is recommended by Xdebug's creator to avoid doing so, because it will slow down your applications if you do not need to debug (you should use the appropriate Chrome, Firefox or Safari extension to activate debugging). Your problem is probably due to the fact that xdebug.start_with_request has a value of yes and/or that your IDE key has not been defined. If I recall correctly, you will get the error you have right if xdebug.start_with_request is set to yes, but if you don't define your IDE key, Xdebug won't work if you start the listener and run a command that has a breakpoint somewhere in its execution (breakpoint is never hit).

SmyGeb05's avatar

thank you. since I already have worked in my project, wouldn't the best way to proceed be editing the .ini file instead of changing the docker files? the changes would be in the php.ini file, yes? or would I need to change the /etc/php/8.0/cli/conf.d/20-xdebug.ini,'

incidentally, what is the best way to edit either of these ini files. There is no text editor that I can find to manipulate files within the container or volume (I get them confused). Is it possible to install VIM into the container so these files, or file, can be edited?

rbd

piljac1's avatar

I have never used Docker or Sail, so I can't help you with that unfortunately... Hopefully someone else can.

SmyGeb05's avatar

thank you for helping as much as you have.

AlexanderWright's avatar

I think you can edit the PHP container runtime here:

my_project/vendor/laravel/sail/runtimes/8.0/php.ini

Then run: sail build --no-cache

Please or to participate in this conversation.