Sunday, May 2, 2010

Remote Debugging Eclipse

Recently I ran into a nasty bug that will get reproduced only in host Eclipse 1.The best way to catch them is by remote debugging.

Remote Debugging
Remote debugging is a java feature. Since Eclipse is java application (running inside a JVM) we can remote debug it given the JVM used to launch Eclipse supports it. Most JVMs supports remote debugging from pre-1.4 era.

WebSphere give a nice definition "Debugging a program running on one system while controlling the program from another system is known as remote debugging. The debugger supports remote debugging by allowing you to run the debugger user interface on one system, while running the debug engine on another system. The system running the debugger user interface is known as the local system. The system where the debug engine runs is known as the remote system."

How to remote debug Eclipse?
  1. Start the Eclipse as server
  2. We need to pass -Xdebug VM argument to Eclipse to tell JVM to get launched with debugger. We need to pass certain more options to tell it to start in server mode and listen to a particular socket.

    This command shall be entered on the command prompt
    eclipse.exe -vmargs -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044 


    See the complete details for the options and their meaning at Connection and Invocation Details page.

  3. Creating a Remote Java Application debug config
  4. Start another instance of Eclipse where we will debug the other instance launched in Step 1. Also check out the code that you want to debug. Once this is done, open debug launch configurations and choose 'Remote Java Application' and create a new debug config.

    The project text box shall contain the project which has the code that needs to be debugged. The connection type shall be standard socket attach while port will contain the socket address we gave in Step 1. The host is localhost we both instances are running of same machine.

  5. Connecting and attaching to the remote server
  6. Launch the debug config like any other debug config. This will launch the debug mode. Place the breakpoints and do the relevant actions in the server Eclipse instance to hit the.

  7. Debugging
  8. The debug process is same as normal debug. No differences. However, if you change the code then the updated code is not what that would run. Remember the server Eclipse is still running in separate JVM. So what you are getting is only a reflection of the code execution. The debug session will end when the serve Eclipse instance is closed or the client Eclipse is disconnected using the disconnect button in the debug view.
1. Host Eclipse: The default eclipse instance is referred to as Host Eclipse. When self-hosting, a new Eclipse is launched from it, it is referred to as Guest Eclipse or Nested Eclipse Instance.


  1. Very useful stuff. A while ago, I created a wiki page with advanced techniques like this, mostly so that I knew where to look when I needed to remind myself:

    Btwm, by using "suspend=y" the instance being debugged will be paused at startup until a debugger is attached and execution is resumed from within the debugger.

    The most extreme (and fun) version of this is when you attach the Eclipse debugger to the currently running instance itself, see:

  2. Thanks, it simple and effective :-)

  3. Anonymous11:10 AM

    Nice article , just to add I would suggest start up script to put JVM debug parameter and use a variable e.g. isDebugEnabled and also REMOTE_DEBUG_PORT in the script and export this variable when you want to remote debug your Java application. This will be very handy and will require just one time setup work.

    How to setup remote debugging in Eclipse

  4. Anonymous8:11 AM

    You need to ensure that you run the same codebase in eclipse which is deployed in your remote machine so that what you debug and see in eclipse is true and real. you also need to ensure that your code is compile with debug option "-g" so that eclipse can easily gather debug info. I have also written a blog post about eclipse remote debugging which talks about setting up eclipse for remote debugging and issues faced during remoted debuggin, you may find it interesting.

  5. Nice article. I have also written a blog post about eclipse remote debugging which talks about setting up eclipse for remote debugging and issues faced during remote debugging, you may find it interesting.