Remote debugging of tomcat using eclipse

If you are running tomcat on a remote machine and you want to debug the application running on the remote tomcat using eclipse on your local machine then this is the guide for you.

Tomcat remote debug

Configure tomcat

The first step would be to add the following properties to the in the tomcat/bin/ folder. This file doesn’t exist by default in tomcat 7 so you may have to create this file and give appropriate user rights:

export CATALINA_OPTS="$CATALINA_OPTS -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"

You can change the port by changing the value of the address attribute above.

You would need to restart the tomcat after making the changes. And you should see the below message in the catalina.out log file.

Listening for transport dt_socket at address: 8000



Eclipse remote java application configuration

Steps for configuration

1. Go to the run menu in eclipse and click the Debug Configurations menu as shown in below screenshot.

eclipse run menu
Eclipse run menu

2. You would see the Debug Configuration dialog as shown in below

Eclipse debug configuration dialog
Eclipse debug configuration dialog

3. Select the Remote Java Application in the dialog and you will the below dialog. If you are not seeing the Remote Java application menu item then you are probably in run configuration, you need to switch to Debug configuration..

Remote Java application configuration
Remote Java application configuration


3. Fill the dialog:

  • Name : enter the name you like, a name you remember to which tomcat you are connetiing
  • Project: would be the workspace project you want to act as source project for debugging.
  • Connection Type: Choose Standard (Socket Attach)
  • Connection properties:
    • Host is the name or IP of the remote machine
    • Port is the port you configured above in the tomcat
  • If you have to add more than  one project as the source folder go to the source tab and add the project you want

Once you have followed the above steps, you should be able to debug the remote app using your eclipse.

Common issues

Connection Refused

You may be seeing the below message in eclipse when trying to connect.

Message: <code>;“Failed to connect to remote VM. Connection Refused”

Things that you can do to resolve the above error:-

  1. Look if the tomcat is running.
  2. Look that you have provided the right hostname and port in the eclipse Connection properties
  3. The most common cause for this issue is that you have not configured the tomcat correctly.  Try repeating the first step of configuring tomcat. Look that you have appropriate user rights for the file. Look into the catalina.out file and see if there are any errors.
  4. Your tomcat installation may be behind a firewall so you would have to allow the port in the firewall.

Tips and Tricks

And important trick that i found out while working with eclipse was to make the hot code replacement. It sometimes worked and sometimes not, especially with remote debugging.  Set the break-point right on the beginning of the method in which you want to make changes. Make an actions that executes the code you want to change. As soon as the debugger stops in the method, change the code. And press save. And i bet your code will be hot deployed more often and you will avoid the deployments needed for small changes in code.

If you want to find out about memory leaks please refer to this guide

1 thought on “Remote debugging of tomcat using eclipse”

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.