😎

「Xdebug: [Step Debug] Could not connect to debugging client. 」が出た時のメモ

に公開
PHP
Xdebug
tech

📗 背景

Xdebug 2 から 3 にアップグレードしたところ、以下のようなエラーが発生するようになりました。

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

下記の場合などで困ったので、一旦原因を調査してみることにしました。

  • PHPUnitを実行する際などに、上記のエラーが原因でテストが落ちてしまう
  • 単純にアプリケーションログに混ざってノイズになっている

🔗 Xdebug公式ドキュメント：Xdebug 2系 から 3系 へのアップグレードについて

この時、php.ini 内の Xdebug の設定は以下のように設定していました。

php.ini
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
...

🧠 原因

このエラーの主な原因は、IDE（VSCode や PHPStorm）でデバッガーを起動していないことです。

Xdebug がポート 9003 上で待機しているデバッガーに接続できず、「見つからない」と怒られています。

なぜこうなるのかというと、php.ini上に記載しているXdebugの設定が原因になります。

より詳細に説明すると、

php.ini にて xdebug.start_with_request=yes が設定されている

→ Xdebug が、常時デバッガーへ接続しようとする設定になっている

→ そのため、IDE側でデバッガーが起動していないと、接続に失敗してエラーになる

といった状況です。

🔗 Xdebug公式ドキュメント：xdebug.start_with_request

🛠 対処方法

このエラーを回避するためには、以下のいずれかの方法を取ることができそうです。

✅ 1. 必要なときだけ Xdebug をデバッガーへ接続する設定にする

php.ini で以下のように設定します：

php.ini
xdebug.start_with_request=trigger
...

この設定により、明示的なトリガーがあるときだけ、Xdebug はデバッガーへ接続を試みます。

💡 トリガーの方法

$_ENV / $_GET / $_POST / $_COOKIE に XDEBUG_TRIGGER を含めることで、デバッガーを起動することができます。

🔗 Xdebug公式ドキュメント：xdebug.start_with_request → trigger

トリガーに設定する文字列（XDEBUG_TRIGGER）についても、独自にカスタマイズする事ができます。
🔗 Xdebug公式ドキュメント：trigger_value

例：

XDEBUG_TRIGGERを、$_ENV / $_GET / $_POST / $_COOKIE に含めてトリガーする方法をいくつか紹介します。

ブラウザ拡張（例：Xdebug Helper）を使う方法
JetBrains製のブラウザ拡張が利用できそうでした。
↳ JetBrains公式ガイド

クエリパラメータで明示する方法
↳ ?XDEBUG_TRIGGER=1をパスの最後尾につける
例）https://fuga.jp/hogehoge?XDEBUG_TRIGGER=1

シェルからPHPファイルを実行する方法
↳ 実行時にパラメータを渡す

XDEBUG_TRIGGER=1 php index.php

🚫 2. エラーログを出力しないようにする

Xdebug 側でログレベルを下げることで、接続失敗のエラーログを抑制することも可能です。

php.ini
xdebug.log_level=0
...

また、エラーログの出力先を変更することで、アプリケーションログに影響を与えないようにすることも可能です。

php.ini
xdebug.log = /tmp/xdebug.log
...

⚠️ ただし、根本的な解決にはならないので注意です。

🔍 参考になったサイト

上記の調査をする際に、下記の方のブログが大変参考になりました🙏

Discussion