Java Remote Debug with Eclipse

Debugging a remotely running Java application using Eclipse IDE is an important skill in our Java debug arsenal. Eclipse IDE is what I use mostly and so I took it for example. Configuring the same for debug with other IDEs like NetBeans, IntelliJ should be similar.

We will need this remote debug mechanism when the application is running separately outside of IDE. Mostly when the application might be in different system in the network. We will have the source or project configured in IDE in our system. Scenarios include, issue coming only in some X system and application working good in other systems. In that case, we want to remotely debug the application running in that X system.

This is a how-to tutorial and if you know how to remote debug a Java application using Eclipse, please terminate reading this, you may not find anything interesting and finally you will blame me, saying you didn’t expect a so basic article from me. If you are looking for Eclipse debugging tips in general, you can refer to this earlier written super hit article.

To debug remote Java application

Step 1: Start the application in debugging mode

java -Xdebug -runjdwp:transport=dt_socket, server=y, suspend=n, address=<debug-port> <ClassName>

• server=y – Java application should be a TCP/IP server and wait for connections
• suspend=y – the Java application (now server) will pause on start up and wait for debugger to join. If ‘n‘, application will not wait for debugger at start up, instead it will run as usual and when IDE encounters breakpoint it will fork the application.
• address=<debug-port> – a port number on which the debugger will join to debug the application. Remember, this should be a port that is not already in use.
• ClassName – Java application main-class name. If we have a jar we can include that with appropriate classpath.

Step 2: Configure and Start Eclipse in Remote Debugging Mode

1. First we should have the project source in place. Keep the breakpoints wherever necessary.
2. Go to Run –> Debug Configurations –> Remote Java Application
   
3. Create ‘New’ remote java application and give the Host and Port. Host is the IP of the machine where the remote java application is running. If the application is running in the same machine, then we can give localhost. Then the port which we have given while starting the application in remote mode.
   
4. Now click ‘Debug’ to start debugging the remote java application.

Example Remote Java Application Debugging

package com.javapapers.java;

import java.awt.Color;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JPanel;

public class DebugRemote {
	public static void main(String args[]) throws InterruptedException {

		final JFrame frame = new JFrame("Remote Debug Demo");
		JPanel panel = new JPanel();
		final JButton btn = new JButton("On");
		btn.setBackground(new Color(50, 200, 100));
		frame.getContentPane().add(panel);
		panel.add(btn);
		frame.setVisible(true);
		frame.pack();
		btn.addActionListener(new ActionListener() {
			public void actionPerformed(ActionEvent arg0) {
				if ("On".equals(btn.getText())) {
					btn.setText("Off");
					btn.setBackground(new Color(200, 50, 100));
				} else {
					btn.setText("On");
					btn.setBackground(new Color(50, 200, 100));
				}
			}
		});
	}
}

I am running the above program in Java remote debug mode.

Example remote debug application start:
java -Xdebug -runjdwp:transport=dt_socket, server=y, suspend=n, address=6666 com.javapapers.java.DebugRemote

Now, I have kept the break point inside the action listener method and so on click of the button, Eclipse wakes up on debug mode and I get control for remote debugging.

Java Remote Debugging Issues

• If the project source and the running application is not in sync, the remote debugging may not work as expected. Breakpoints will not pause as we expect.
• Avoid remote debugging an application in production. As things might break and data can go to inconsistent state.
• Eclipse says, “Failed to connect to remote VM. Connection refused”. In this kind of issue,
• first check if the stove is switched on (check if the remote Java application is running),
• any firewall blocking access to the host running the remote application,
• cross check the JVM options that needs to be supplied when remote application is started
• When we start the java application in remote debug, we should double check the port number given in options. Ensure the same port number is not used by any other application.