Friday, February 25, 2011

How to setup Java remote debugging in Eclipse

How to remote debug Java program in Eclipse
Remote debugging is not a new concept and many of you are aware of this just for who don’t know what is remote debugging? It’s a way of debugging any process could be Java or C++ running on some other location on your development machine.  Since debugging Java application is an essential part of Java development and ability to debug your application not only saves time but also increase productivity. Local debugging is the best way to debug Java program in my opinion and should always be preferred over remote debugging as discussed in my post How to debug Java program in Eclipse, but if local debugging is not possible and there is no way to debug your process then remote debugging Java application is the solution.  

All Major IDE like NetBeans, Eclipse, IntelliJ allows you to remote debug Java program but I mostly use Eclipse for remote debugging Java application because it's free and standard IDE in Investment banks for Java projects. By the this is second article on Eclipse IDE in Javarevisited after sharing Top 30 Eclipse keyboard shortcuts to improve productivity in the previous post.

When use Java remote debugging in Eclipse

Many of us work on a Java project which runs on Linux operating system and we do development mostly on Windows using Eclipse IDE. Since I am working in Investment banking and finance domain I have seen the use of Linux server for running electronic trading application quite a lot, which makes Java development difficult because you don't have code running on your development machine. 

Sometimes we managed to run the Java project in Eclipse IDE in windows itself which are essential for development and debugging purpose but many times it's not possible due to various reason e.g. your project depends upon some of the platform dependent library or some Linux module whose windows version may not be available or your project is too big to run on windows and it's heavily connected to upstream and downstream system and it's almost impossible to create the same environment in your windows machine for development. 

On such situation my approach to work is isolate the work I am doing and test that with the help of mock objects, Threads or by trying to run that module independently but this is also not the desired solution in some cases where you need to debug the Java project at run time to find out some subtle issues, This is the time to use Eclipse for remote debugging Java application.

Eclipse IDE provides us most useful feature called "Remote debugging" by using which you can debug Java application running on remote Linux or Windows Server from your windows machine. believe me, this becomes absolutely necessary in some condition and knowing how to setup remote debugging and working of remote debugging in eclipse can greatly improve your productivity. In this Eclipse tutorial, I will try to explain eclipse remote debugging or how to setup remote debugging in eclipse.

Now let's see how we can setup remote debugging in Eclipse:

1) First setup your Java project in Eclipse.

2) Select your project, go to "Run" Menu option and select "Debug Configurations"

remote debugging eclipse
Remote debugging with eclipse 1

3) This will open Debug Configuration window select "Remote Java Application" icon on the left side, Right click and say "New".

How to do  remote debugging in eclipse
eclipse remote debugging 2

4) After clicking on New, Eclipse will create Remote Java Application configuration for your selected project. Now next step is to setup host and port for remote debugging in Eclipse.

How to setup Java remote debugging in Eclipse
Remote debugging in Eclipse 3

5) Now put the hostname and port on which your process is listening for the debugger in Linux machine. Check the "Allow termination of remote VM" checkbox if you would like to close java application running on Linux from eclipse.

6) Now you are all set to remote debug your Java project from Eclipse IDE but before starting to debug make sure your Java process is started with Java remote debug settings and listening on the same host and port, otherwise eclipse will not able to connect successfully.

7) To debug just click the "Debug" button in the last screen where we have set up host and port.

8) You can also debug by going to "Debug Configurations" selecting your project in "Remote Java Application” and clicking on "DEBUG".

Java remote debug setting and JVM debugs options

In order to remote debug a Java application from Eclipse, that application must be started with following JVM debug options:

java -Xdebug -Xrunjdwp:transport=dt_socket,address=8001,server=y  suspend=y -jar stockTradingGUI.jar

This will start java application stockTradingGUI into debug mode using Java Debug Wire Protocol (JDWP) protocol and it will listen on port 8001 suspend=y will ensure that that application will not start running until Eclipse connects it on a specified debug port.It also important to note that application must be started before Eclipse tries to connect it otherwise Eclipse will throw an error "Failed to connect to remote VM. Connection refused" or "Connection refused: connect

Enjoy remote debugging in Eclipse J

How to fix "Failed to connect to remote VM. Connection refused"

"Failed to connect to remote VM. Connection refused"  is the most common error Java programmer face while trying to remote debug Java application, there can be multiple reasons why you are getting "Failed to connect to remote VM. Connection refused" error, here are some of the reason  this error occurs in Eclipse:

1) Network or Firewall issue
Since Eclipse uses TCP socket connection to connect to the remote machine, remote host must be accessible from your network and corresponding remote debug port must be open and ready to accept the connection. You can check this by using networking commands in windows and Linux like ping or telnet.

2) Java application not running on remote host
This is probably the most common reason of "Failed to connect to remote VM. Connection refused". If Java application is not running there will no one to accept the connection. Just restart the Java application in debug mode.

3) Incorrect host and port combination
One of the human error which causes "Failed to connect to remote VM. Connection refused". Some time typo on hostname or port causes Eclipse trying to connect different servers or a different port, which is an obvious reason you get this error.

4) Missing JVM debug settings
In order to accept remote connection from Eclipse your Java application must be running with correct debug settings based upon your JVM. If you are JVM is not running on debug mode you will get "Failed to connect to remote VM. Connection refused"

Java Remote debugging Tips  in Eclipse IDE

Here are few tips which is very useful while remote debugging any Java program into Eclipse IDE, this not only help you to avoid some common errors in Eclipse but also makes remote debugging much easier:

Tip: In JVM DEBUG parameters there is a parameter called "suspend" which takes the value as "y" or "n". so if you want to debug the process from the start set this parameter as  "suspend=y" and your Java application will wait until Eclipse remotely connects to it. Otherwise, if you want to run your program and later want eclipse to be connected that set this as "suspend=n" so your java application will run normally and after eclipse remotely connected to it, it will stop on breakpoints.

Tip: Use startup script to put JVM debug parameter and use a variable e.g. isDebugEnabled and also REMOTE_DEBUG_PORT in the shell 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.

Tip: if you get the error "Failed to connect to remote VM. Connection refused" or "Connection refused: connect" then there might be two possibilities one your java program is not running on the remote host and other you are giving incorrect port or hostname after verifying these two things if the issue still persists then try giving the full name of the host.

Tip: You also need to ensure that you run the same code base in eclipse which is deployed on 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 compiled with debug option "-g" so that eclipse can easily gather debug info e.g. information about the local variable. by default java only generate  line numbers and source file information.with  debug option -g your class file size might be more because it would contain some debug information.

Note: Recently I have wrote another article 10 tips on debugging Java Program in eclipse which is a collection of my java debugging tips and explains some advanced java debugging concept like conditional breakpoint, how to debug multithreaded programs in Java, Step filtering to avoid debugging system classes in Java, logical view to see the content of collection classes like HashMap or ArrayList in Java.

Further Learning
The Eclipse Guided Tour - Part 1 and 2
Java Fundamentals, Part 1 and 2
The Java Developer's Guide to Eclipse

Other Java Eclipse articles you may like to explore
  • 30 Useful Eclipse Shortcuts for Java Developers (list)
  • How to remote debug Java application in Eclipse? (tutorial)
  • 10 Eclipse debugging tips Java developer should know? (see here)
  • How to attach source code for JAR file in Eclipse? (guide)
  • Eclipse shortcut to print System.out.println statements? (shortcut)
  • How to increase console buffer size in Eclipse? (steps)
  • How to use spaces instead of tabs in Eclipse? (guide)
  • How to create an executable JAR file from Eclipse? (example)
  • 3 Books to Learn Eclipse IDE for Java developers (list)

Thanks for reading this article so far. If you like this article then please share with your friends and colleagues. If you have any question or feedback then please drop a comment.


Anonymous said...

Thanks buddy. I was struggling with setting up remote debugging in eclipse from past few hours you save my day.

Amit said...

Agree.In our investment banking project , we heavily use Eclipse remote debugging for development and debugging purpose.

Robert Bram said...

Fantastic article. When I am in a Java app, bring able to halt the app, inspect and modify variables and run arbitrary code against the system in it's halted state is just brilliant - a billion times better than System.out.println statements!

This is a good match for my article on debugging Alfresco with Eclipse.

Anonymous said...

Hi I am trying to remote debug my java application running on solaris machine but remote debugging is not working for me, I am getting following error when I try to connect eclipse to my remote machine:
"Failed to connect to remote VM. Connection refused." Connection refused: connect "

Can any one help please, I found eclipse remote debugging really hard to setup

Javin said...

you will get "Failed to connect to remote VM. Connection refused" error if you are trying to connect your java application from eclipse but it is not running on remote host. remote debugging in java is trick stuff especially if you are setting it up.

Bob Foster said...

"before starting to debug make sure your java process is started with java debug settings and listening on same host and port, otherwise eclipse will not able to connect successfully"

What are the Java debug settings????

Javin @ how to debug java program said...

Hi Bob, to remote debug a java application , that application must be start in debug mode with following options provided to JVM:

-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=8001,server=y,suspend=n

This will make your java application to listen on 8001 port and eclipse can connect on that port.

Tiago said...

I am trying to remote debug. My java application server is running with OC4J but remote debugging is not working for me, I am getting following error when I try to connect eclipse to my remote machine:
"Failed to connect to remote VM
com.sun.jdi.connect.spi.ClosedConnectionException "

Can any one help please

Anonymous said...

"Failed to connect to remote VM" comes when you try to connect a Remote Java application from Eclipse and That remote application is down. make sure remote app is up before you connect it from Eclipse. Remote debugging in Java is fantastic and just work for me every time.

Anonymous said...

This article really helped me get started, but now I am running into an issue that I do not know how to resolve.
I can run the apllication as a runnable .jar, but when I try to activate with remote debugging I get the following from Eclipse.

Thread [main] (Suspended (exception ClassNotFoundException))
URLClassLoader$ line: 217
AccessController.doPrivileged(PrivilegedExceptionAction, AccessControlContext) line: not available [native method]
Launcher$AppClassLoader(URLClassLoader).findClass(String) line: 205
Launcher$AppClassLoader(ClassLoader).loadClass(String, boolean) line: 323
Launcher$AppClassLoader.loadClass(String, boolean) line: 294
Launcher$AppClassLoader(ClassLoader).loadClass(String) line: 268
Launcher$AppClassLoader(ClassLoader).loadClassInternal(String) line: 336

On the remote side I see
Exception in thread "main" java.lang.NoClassDefFoundError: suspend=y
Caused by: java.lang.ClassNotFoundException: suspend=y
at Method)
at java.lang.ClassLoader.loadClass(
at sun.misc.Launcher$AppClassLoader.loadClass(
at java.lang.ClassLoader.loadClass(
at java.lang.ClassLoader.loadClassInternal(

Any ideas sure would be appreciated.

Raji said...

I really like this Java tutorial, its detailed and step by step guide for remote debugging in Java. I didn't know about powerful Java remote debugging before but after reading this article and setting up remote debugging for my current project, Now I have better control over my development and debugging process. Thanks and please continue writing on Java and remote debugging.

Anonymous said...

Java remote debugging is very tough to setup and get it right, I have been struggling with Java remote debugging options but nothing is working for me,I am running my java application on Redhat linux server and eclipse on my windows7 desktop. please help/

Nobody said...

I have used that in android system application development and testing on the actual android device. Its really a great facility in eclipse.

Anonymous said...

Remote debugging Java programs is great facility Java developers enjoys otherwise it would have been difficult to develop and debug Java applications running on remote servers.

abhishek joshi said...

under debug configurations --->connect window---->
project is not getting listed.

Javin @ hashtable examples in Java said...

@abhishek you don't need project there, you need to create debug configuration by yourself as shown in above tutorial. let me know if you have different problem.

Anonymous said...

Are you missing a comma before suspend=y?

i.e. should the command be:

java -Xdebug -Xrunjdwp:transport=dt_socket,address=8001,server=y,suspend=y -jar stockTradingGUI.jar

I spent a few hours failing to debug a simple class - getting the same error as Anonymous:

Exception in thread "main" java.lang.NoClassDefFoundError: suspend=y

When I added the comma, it started to work.

Sachin said...

I don't prefer remote debugging neither with Eclipse nor with IntelliJ, if you have option to locally debug it. I write main classes to test the stuff and quickly run a part of program instead of waiting for application to start and reach the point because it takes too much time and if you have slow network you will just spend whole day to reaching the point where your code fail rather than immediate debugging and solution. Think carefully about your debugging strategy, Java provides lots of option in terms of JUnit test, testing with main method, Using Threads to input messages and just some kind of creating improvisation. Nevertheless remote debugging should be your last arsenal because it offer something which is not available on other method, i.e. real application debugging. Also look on JDB and JPDA for more details

Anonymous said...

"main classes to test the stuff and quickly run a part of program instead of waiting for application to start and reach the point because it takes too much time "

Read more:


It takes to much time? Are you kidding me?
Writing main-class-tests takes to much time. Write JUnit tests instead, when you want to save time. And if you have to make a programm working on a remote environment you will be greatful for a peek inside it

Once you get a chance to work with a legacy-enterprise-webapp, you will start to love remote debugging (logs help a bit, more in finding good breakpoints)

Anonymous said...

Hi, thanks for the guide.
There is a missing comma in the command near to suspend=y.
The right command is:
java -Xdebug -Xrunjdwp:transport=dt_socket,address=,server=y,suspend=y -jar FileName.jar

Anonymous said...

There is one more error message that i got "Failed to connect to remote VM. Connection timed out".
I got this error because the firewall of the remote machine was turned on.

Krishna (KP) said...

Thanks for this quick reference guide for remote debugging in Java.

There is a comma missing in the command for starting the application in remote machine. The correct command is:
java -Xdebug -Xrunjdwp:transport=dt_socket,address=8001,server=y,suspend=y -jar stockTradingGUI.jar


I have used this
java -Xdebug -Xrunjdwp:transport=dt_socket,address=8001,server=y,suspend=y -jar stockTradingGUI.jar
even then its not working.
remote machine's firewall is switched off.
it says: Failed to connect to remote VM
Please help me


I should specify remote machine's port no. na? and shud I check "allow terminaton of remote vm" or not?? plz help..

Unknown said...

This is useful guide. Thank you very much!

rasengan said...

Remote debugging hasn't been a challenge until recently when my java code includes a dll which also I'm required to remote debug. Any inputs are highly appreciated.

Anonymous said...

Thank you. For years I've been remote debugging with just the suspend=y option, now it doesn't work any more, I read your post, add the server=y and it works like a charm.

Ashish said...

There is another possibility that the connection will get refuse which is if another person is already connected to the application in the debug mode and later you are trying to connect or trying to debug remotely.

New learner said...

As I am new to remote debugging I want to debug the code from dev server to local eclipse is that possible

Kamlesh Sahani said...

Debugging is happening but step into,step over and step return is disable how can I resolve it I am using appinventor project with eclipse

Javin Paul said...

@Kamlesh, does code is stopping at the breakpoint? If yes, then as soon as it stops the step into, step over option will get enabled.

Post a Comment