Step-by-step: How to do Xdebug troubleshooting connection to client IDE

Question

This is something I would definitely want to include in the Xdebug documentation. I think it would work best to have many people collaborate on this, so I've created a file in the xdebug.org github repository (https://github.com/derickr/xdebug.org/blob/master/html/docs/tutorials/troubleshooting.rest) to collect tips. Feel free to fork and extend!

On the Xdebug side, in the upcoming version (2.2) it already dumps in its xdebug.remote_log file a couple of extra diagnostics such as whether it tried to connect and whether the connection was accepted or denied.

You can use the debugclient utility to determine if the client can receive Xdebug connections, as you can read in the Xdebug documentation:

Before you start your script you will need to tell your client that it can receive debug connections, please refer to the documentation of the specific client on how to do this. To use the bundled client simply start it after compiling and installing it. You can start it by running "debugclient". If you want to use the GDB commandset to debug your scripts, make sure you use a debugclient as bundled with Xdebug 1.3 as the one bundled with Xdebug 2 only works with the DBGp commandset. When the debugclient starts it will show the following information and then waits until a connection is initiated by the debug server:

Xdebug Simple DBGp client (0.10.0)
Copyright 2002-2007 by Derick Rethans.
- libedit support: enabled
Waiting for debug server to connect.

After a connection is made the output of the debug server is shown:

Connect
<?xml version="1.0" encoding="iso-8859-1"?>
<init xmlns="urn:debugger_protocol_v1"
      xmlns:xdebug="http://xdebug.org/dbgp/xdebug"
      fileuri="file:///home/httpd/www.xdebug.org/html/docs/index.php"
      language="PHP"
      protocol_version="1.0"
      appid="13202"
      idekey="derick">
  <engine version="2.0.0RC4-dev"><![CDATA[Xdebug]]></engine>
  <author><![CDATA[Derick Rethans]]></author>
  <url><![CDATA[http://xdebug.org]]></url>
  <copyright><![CDATA[Copyright (c) 2002-2007 by Derick Rethans]]></copyright>
</init>
(cmd)

You can find more information about the Xdebug 2 initialization protocol here.
A further reference: Howto check xdebug installation.
Unfortunately the debugclient utility is provided only in source form, so you have to build the executable by yourself; this can be done either on Linux (see INSTALL) and Windows (with Visual Studio - see debugclient.dsp).
XAMPP includes a compiled version in xampp/php/debugclient.exe.

Netbeans has a very thorough documentation that also covers how to troubleshoot such problems:

http://wiki.netbeans.org/HowToConfigureXDebug

Windows users disable your firewall and then try again. If it works, allow Java(TM) Platform SE binary through firewall then enable it again. It will work just fine!

Thank you for the commands, they were very useful on debugging.

be careful about firewalls for remote debug sessions. I diagnosed my problem by using telnet to checkout 9000 port status and found that preventations by firewall.