IntelliJ IDEA 2023.1 Help

Remote debugging via SSH tunnel

This tutorial describes how to use an SSH tunnel to setup a secure connection between the development machine and a remote server. This can be useful for debugging code on a remote machine when there are firewalls in between, or a NAT router prevents direct connection, or the ISP or network infrastructure does not allow incoming TCP connections to the developer machine.

Install the PHP plugin

This functionality relies on the PHP plugin, which you need to install and enable.

  1. Press Ctrl+Alt+S to open the IDE settings and select Plugins.

  2. Open the Marketplace tab, find the PHP plugin, and click Install (restart the IDE if prompted).

Prepare the debugging engine

Before you start debugging, make sure that you have a debugging engine installed and configured properly. IntelliJ IDEA supports debugging with two most popular tools: Xdebug and Zend Debugger. These tools cannot be used simultaneously because they block each other. To avoid this problem, you need to update the corresponding sections in the php.ini file as described in Configure Xdebug and Configure Zend Debugger.

Open the active php.ini file in the editor:

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

  2. On the PHP reference 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.

When using Xdebug, make sure at least the following settings are specified:

[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>"
[xdebug] zend_extension="<path to xdebug extension>" xdebug.remote_enable=1 xdebug.remote_host= xdebug.remote_port="<the port (9000 by default) to which Xdebug connects>"

Listening for incoming debugger connections

In IntelliJ IDEA, enable listening to incoming debug connections by either clicking the Start Listening for PHP Debug Connections button on the toolbar/the status bar 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 dialog Ctrl+Alt+S.

Set up an SSH tunnel to the remote machine

What we want to do is connect to the remote machine over SSH and set up port forwarding for port 9000 (for Xdebug 2), 9003 (for Xdebug 3), or 10137 (Zend Debugger). The idea is to create a "virtual" TCP port on the remote server that sends its traffic to a TCP port on our own machine, tunneling traffic over SSH.

SSH tunnel diagram

The SSH tunnel is used for connecting through a firewall and establishing a secure connection between the remote server and the developer machine. When the remote server can connect to the developer machine directly (for example, with a Vagrant machine), an SSH tunnel may not be needed.

In this case, we need to make the debugger connect back to the developer machine by setting xdebug.remote_host=ip_address (for Xdebug 2), xdebug.client_host=ip_address (for Xdebug 3) or making sure the debug host is the IP address of the developer machine (for Zend Debugger). This can be done using the IntelliJ IDEA bookmarklets, a Browser Debugging Extension, or the techniques outlined in Debugging PHP CLI scripts with IntelliJ IDEA.

Set up an SSH tunnel

  • Run the following command on the command line:

    ssh -R 9003:localhost:9003 username@hostname
    ssh -R 9000:localhost:9000 username@hostname
    ssh -R 10137:localhost:10137 username@hostname


Once the SSH tunnel is set up, we can start debugging using zero-configuration debugging with Xdebug or Zend Debugger. When the debugger is started, IntelliJ IDEA will prompt to accept the incoming connection.

Incoming debugger connection Xdebug

Once we accept it, we will be able to debug using the techniques outlined in Examine suspended program.

Debug PHP CLI scripts with remote PHP interpreters or via SSH tunnel

When a remote PHP interpreter is properly configured, it's possible to create a run/debug configuration taking advantage of the remote PHP interpreter for debugging.

When the SSH tunnel is up and running, we can also debug PHP CLI scripts. Since the debugger runs on a remote machine, starting a CLI debugging session can be done by using PHP command line switches or using environment variables (on the remote machine). This workflow is not the officially recommended way of debugging, though it might be useful in some cases when the debugging session is needed to be established from the remote server side.


The debugger never connects or refuses the connection

When the debugger never connects or refuses the connection, check the following:

  • Make sure Xdebug is configured to connect to and port 9000 (for Xdebug 2) or port 9003 (for Xdebug 3).

  • When using Zend Debugger, make sure the IntelliJ IDEA bookmarklets or Browser Debugging Extension is configured to connect to

  • Make sure IntelliJ IDEA is listening for incoming debugger connections prior to setting up the SSH tunnel.

  • When a machine is rebooted or the connection is lost, the SSH tunnel has to be reestablished.

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

Last modified: 14 March 2023