IntelliJ IDEA 2021.2 Help

Multiuser debugging via Xdebug proxies

When you start a debugging session, the Xdebug extension connects to the IP address IntelliJ IDEA is running at, specified as the xdebug.remote_host (for Xdebug 2) or xdebug.client_host (for Xdebug 3) value. IntelliJ IDEA accepts this connection and can communicate with Xdebug over it. Xdebug only supports connecting to a single IP address, and does not automatically connect back to the IP address that runs the browser because of security reasons. To debug PHP applications in multiuser environments, Xdebug offers a so-called DBGp proxy.

When a proxy is used, the PHP Xdebug extension no longer connects to IntelliJ IDEA directly, but instead connects to the DBGp proxy server. All developers in the team, in turn, then connect to that proxy. Each developer has a separate debugging session running over this proxy, which makes it possible to do multi-user debugging of the same code on the same server.

Ps Xdebug Schema Proxy

Configure multiuser debugging via an Xdebug proxy (DBGp) server

Download and install a DBGp proxy

To be able to start a debugging session, you'll need to have a DBGp proxy running on a server that can be reached by the web server itself as well as all developer machines. We can install the proxy on the web server, on a machine in the same network, or a machine accessible via an SSH tunnel.

  1. Download the dbgpProxy executable file for your platform on the DBGp Proxy Tool downloads page.

  2. Start the DBGp proxy either on the web server or on a machine that can communicate both with the web server and all developer machines. The DBGp proxy executable accepts two main arguments:

    • -i: the host and the port to listen on for IDE (client) connections

    • -s: the host and the port to listen on for debugger engine (server) connections

    See DBGp Proxy Tool documentation for details.

    In the following example, we start a proxy that listens for debugger connections on the loopback address and port 9001, and listens for developers on the machine IP address and port 9000.

    dbgpProxy.exe -i -s
    ./dbgpProxy-macos -i -s
    ./dbgpProxy -i -s

    The DBGp proxy will confirm these settings when started:

    Ps Pdgp Running

Make sure Xdebug is installed and configured on the web server

  1. Open the active php.ini file in the editor:

    1. In the Settings/Preferences dialog Ctrl+Alt+S, click PHP under Languages & Frameworks.

    2. On the PHP page that opens, click the Browse button next to the CLI Interpreter field.

    3. In the CLI Interpreters dialog that opens, the Configuration file read-only field shows the path to the active php.ini file. Click Open in Editor.

  2. Make sure that at least the following settings are specified:

    [xdebug] zend_extension="<path to xdebug extension>" xdebug.remote_enable=1 xdebug.remote_host=dbgp_proxy_hostname_or_ip xdebug.remote_port="<the port (9000 by default) to which Xdebug connects>"
    [xdebug] zend_extension="<path to xdebug extension>" xdebug.mode=debug xdebug.client_host= xdebug.client_port="<the port (9003 by default) to which Xdebug connects>"

For details on configuring Xdebug, refer to Configure Xdebug.

Configure access to the DBGp proxy server from IntelliJ IDEA

  1. In the main menu, select Tools | DBGp Proxy | Register IDE.

  2. In the DBGP Proxy dialog that opens, specify the IDE key value (this should be a unique value for each developer, as it identifies the debugging session), the host and port of the Xdebug proxy server.

    Pdgp Register Ide
  3. Click OK to connect to the specified proxy server. The server registers the credentials, and confirms the connection.

    Pdgp Register Ide Connected

    IntelliJ IDEA will notify about the successful connection, too.

    Pdgp Register Ide Successful
  4. To update the existing credentials, select Tools | DBGp Proxy | Configuration in the main menu. In the DBGp Proxy dialog that opens, edit the IDE key, the host, and the port settings.

    To discard the current credentials, select Tools | DBGp Proxy | Cancel IDE Registration in the main menu.

Start a debugging session in the browser

  1. Make sure that the browser debugging extension that you are using is set to the registered IDE key:

    Pdgp Ide Key
  2. In IntelliJ IDEA, enable listening to incoming debug connections by either clicking the Start Listening for PHP Debug Connections button on the toolbar or selecting Run | Start Listening for PHP Debug Connections in the main menu. This will ensure IntelliJ IDEA reacts when a debugging session is started and opens the Debug tool window automatically. Before launching the script, make sure that either a breakpoint is set or the Break at first line in PHP scripts option is enabled on the Debug page of the Settings/Preferences dialog Ctrl+Alt+S.

    Start the debugging session by refreshing the page in the browser.

    Pdgp Debugging Started


Remote file path is not mapped to any file path in project

In some cases, the debugger can connect, but we get the error messages indicating that no mapping between the remote and project files is defined. This means that IntelliJ IDEA cannot determine which local file corresponds to the file being debugged.

No mappings configured

We can solve this problem by clicking Click to set up path mappings and providing the necessary path mappings.

Additionally, we can configure these mappings using the techniques outlined in Configure synchronization with a Web server.

No connection could be made because the target machine actively refused it

  • Make sure that IntelliJ IDEA has been registered with the DBGp proxy, and it is listening for incoming debugger connections.

  • Make sure that the correct IDE key is set in IntelliJ IDEA and in the debugger bookmarklet or browser extension.

  • Is there a firewall blocking connections to the DBGp proxy? If so, make sure the PHP Xdebug extension can connect to it, as well as the developer machines. You can use or a similar service to check for opened inbound ports.

  • Is there a firewall blocking connections to the IDE? Make sure that IntelliJ IDEA can be connected to from the DBGp proxy machine. You can use or a similar service to check for opened inbound ports.

  • The DBGp proxy application binds to the wrong IP address. Run it using as the address so it binds to any IP address on the DBGp proxy server. For example, run dbgpproxy -i -s

When testing multi-user debugging in IntelliJ IDEA with Xdebug and DBGp proxy installed on the same machine, there are some additional things to verify:

  • IntelliJ IDEA binds to the wrong IP address. When a DBGp proxy runs on a local machine where IntelliJ IDEA is also being run, the IDE may be using the wrong network subnet. To fix this, select Tools | DBGp Proxy | Configuration... in the main menu and set DBGp proxy server IP address to Then, try re-registering IntelliJ IDEA with the DBGp proxy.

  • A port conflict exists. When testing DBGp on a local machine, both IntelliJ IDEA and DBGp may want to bind to the same port. Make sure this is not the case by either configuring DBGp to use a different port or changing the IntelliJ IDEA's Xdebug port on the Languages & Frameworks | PHP | Debug page of the Settings/Preferences dialog Ctrl+Alt+S.

Last modified: 02 August 2022