Eclipse Authors: Pat Romanski, Elizabeth White, Liz McMillan, David H Deans, JP Morgenthal

Related Topics: Eclipse

Eclipse: Article

Eclipse Special: Remote Debugging Tomcat & JBoss Apps with Eclipse

So without further ado here is how I use Tomcat, JBoss, and Eclipse to build and debug applications

To view our full selection of recent Eclipse stories click here

Over the last several weeks I've received a few questions about remote debugging with Eclipse. I posted about this on my other blog back in February here but with not enough info for others to follow.

If you go look at that blog entry you will see that I looked into 'in eclipse' debugging but did not find it satisfactory.

So without further ado here is how I use Tomcat, JBoss, and Eclipse to build and debug applications.

Whichever platform you are using (Tomcat or JBoss) you need to start them with the JPDA debugging enabled. For Tomcat this is very easy. In the $CATALINA_HOME/bin directory there is a script catalina.sh. If you provide the arguments 'jpda start' tomcat will startup and listen on port 8000 for a debugger connection.

With JBoss its only slightly more complicated. Basically you need to specify the JAVA_OPTS to have java start up listening for debugger connections. I typically copy the $JBOSS_HOME/bin/run.sh to $JBOSS_HOME/bin/run-debug.sh but you can just as easily setup the JAVA_OPTS environment variable and use the run.sh script.

The value of JAVA_OPTS needs have -Xdebug -Xrunjdwp:server=y, transport=dt_socket,address=4142, suspend=n specified.

So this is what is going on with this argument list

  • Xdebug == start the jvm and listen for debugging connections
  • Xrunjdwp... == the info on how to connect to do remote debugging
  • server=y == start in server mode (i.e. wait for connections, don't go out looking to connect
  • transport=dt_socked == use sockets, this works (I think) only on unix (I'm on a mac), on Windows you have to use shared memory via the transport=dt_shmem argument instead. I'm fairly sure this works but its been a while since I tried it on Windows. YMMV. Here is the official info on the connection arguments
  • address=4142 == the port to connect to or the shared mem address to use
  • suspend=n == don't wait for a debugger to tell you what to do, go ahead and launch

Once you have JBoss or Tomcat running and listening for debugging connections you are good to go for connecting with Eclipse

The first thing you need to do is create a 'debug launch configuration' by bringing up the launch configuration editor. Figure 1 shows the menu item to invoke to make that happen

When the launch config editor appears select 'Remote Java Application' from the 'Configurations:' selection list on the left hand side then click the 'New' button. Figure 2 shows the defaults that appear for me after hitting the 'New' button.

Since it defaults to the Tomcat port leave the port number set to 8000, if yours is different then change it to 8000. Notice also that you can specify the host to connect to. If you have access to the port and the process is running on another machine then you can debug the process remotely. This works out really well for those situations where it works fine in your local env but not in the test env. I usually rename the configuration (it defaults to the name of the project for me) to 'Debug Tomcat' or something like that.

The other options (Source & Common) can be ignored for now. If you have not already launched tomcat in debug mode do so now on the command line with $CATALINA_HOME/bin/catalina.sh jpda start. When its launched go back to the Eclipe launch configuration editor and hit the 'Debug' button. If you are not auto switched to the'Debug' perspective go there now. You should see a 'Debug View' that looks a lot like Figure 3.

Your code should be directly below the Debug View if you have the default layout still in place. If so go there and set a break point in one of your servlets' service methods (or any other code that is being executed in Tomcat, like a struts action or whatever) and then go to the Web browser and tickle the code that you have a break point set in. Notice that Eclipse suspends Tomcat at the breakpoint, comes to the front and lets you debug your program. Everything works just as if you were debugging locally.

Everything works the same within JBoss once you get it started with the debugging turned on. Keep in mind that you must set the port to match (in the above discussion of JAVA_OPTS it is set to 4142). So you need to create a new Debug launch configuration and specify 4142 as the port. Then you can debug your EJBs.

If you'd like to know more about this or you are having trouble making it work feel free to comment or send me an email.

Happy Debugging!

More Stories By Bill Dudney

Bill Dudney is Editor-in-Chief of Eclipse Developer's Journal and serves too as JDJ's Eclipse editor. He is a Practice Leader with Virtuas Solutions and has been doing Java development since late 1996 after he downloaded his first copy of the JDK. Prior to Virtuas, Bill worked for InLine Software on the UML bridge that tied UML Models in Rational Rose and later XMI to the InLine suite of tools. Prior to getting hooked on Java he built software on NeXTStep (precursor to Apple's OSX). He has roughly 15 years of distributed software development experience starting at NASA building software to manage the mass properties of the Space Shuttle.

Comments (32) View Comments

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.

Most Recent Comments
david 01/23/08 11:20:27 AM EST

see link

Srikanth 08/30/07 01:46:38 PM EDT

Thanks A lot....

Manju 08/14/07 01:09:52 PM EDT

This was very helpful. The information is just right

Pasi Shemeikka 12/28/05 08:52:23 AM EST

Hi Bill Dudney,

I really enjoyed reading your blog on Remote Debugging Tomcat & Eclipse Apps with Eclipse.

I would have one problem regarding remote debugging with Jboss as after editing the run.bat JAVA_OPTS section and setting the debug_port I came across very weard looking error message about not been able to initialize dt_socket.

Error [2] in connect() call!
err:: No such file or directory
Socket transport failed to init.
Transport dt_socket failed to initialize, rc = -1.
FATAL ERROR in native method: No transports initialize

I'm using
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_
Java HotSpot(TM) Client VM (build 1.4.2_10-b03)

I appreciate your advice

Best Regards


Pasi Shemeikka 12/28/05 08:51:55 AM EST

Hi Bill Dudney,

I really enjoyed reading your blog on Remote Debugging Tomcat & Eclipse Apps with Eclipse.

I would have one problem regarding remote debugging with Jboss as after editing the run.bat JAVA_OPTS section and setting the debug_port I came across very weard looking error message about not been able to initialize dt_socket.

Error [2] in connect() call!
err:: No such file or directory
Socket transport failed to init.
Transport dt_socket failed to initialize, rc = -1.
FATAL ERROR in native method: No transports initialize

I'm using
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_
Java HotSpot(TM) Client VM (build 1.4.2_10-b03)

I appreciate your advice

Best Regards


Xingsheng 08/31/05 01:19:23 AM EDT

Hi Bill,

When I try to use the eclipse to do a remote debug on a web app on tomcat, I got "Failed to conne`t to remote VM. Connection refused". Any insight on this issue?


manoj 04/10/05 02:05:37 AM EDT

how to do tomcat application server debugging torugh visual slick editor

manoj 04/10/05 02:04:47 AM EDT

i want to do remote tomcat application server debugging through
visual slick edit
can u give some info in this context

Evandro Agnes 09/01/04 10:32:25 AM EDT

It is possible multiple developers debug the application at the same time?

In my environment, the first developer works fine. When the second developer tries to debug the following message appears: Failed to connect to remote VM.

Sorry for english!

mahesh adepu 08/11/04 02:44:44 AM EDT

I can able to debug java code of my webapplication from eclipse.My web application using jsp,struts,castor.How to debug struts & jsp.
Thank you.

mahehs adepu 08/09/04 10:09:44 AM EDT

Thanks for ur reply.I tried by editing run.bat with setting JAVA_OPTS with mentioned parms but i can''t able to debug.Actually i downloaded jboss-ide plugin for eclipse.In the configuration section of jboss-ide i put ''Xdebug -Xrunjdwp:transport=dt_shmem,address=javadebug,suspend=y '' for vm arguments.Then i can debug.It asked for source code container.I browsed and put my code in the container.Now can i able to debug step by step.
Once again thanks for ur reply

Jörg Spilker 08/09/04 06:54:48 AM EDT

Trying to run Jboss with debugging JVM enabled results in the following error during startup:

JBOSS_HOME: /work/12spilk/JBoss JAVA: /usr/opt/java142/bin/java
JAVA_OPTS: -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n -Dprogram.name run.sh CLASSPATH: /work/12spilk/JBoss/bin/run.jar:/usr/opt/java142/lib/tools.jar

Info: Debugging is not available with the Fast VM, invoking the Classic VM.
Info: Debugging is not available with the Fast VM, invoking the Classic VM.
FATAL ERROR in native method: internal error in JVMDI (phantom frame pop)
at java.util.zip.ZipFile.getEntry(Native Method)
at java.util.zip.ZipFile.getEntry(ZipFile.java:140)
at java.util.jar.JarFile.getEntry(JarFile.java:194)
at java.util.jar.JarFile.getJarEntry(JarFile.java:181)
at sun.misc.URLClassPath$JarLoader.getResource(URLClassPath.java:668)
at sun.misc.URLClassPath.getResource(URLClassPath.java:156)
at java.net.URLClassLoader$1.run(URLClassLoader.java:190)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(URLClassLoader.java, Compiled Code)
at java.lang.ClassLoader.loadClass(ClassLoader.java:289)
at java.lang.ClassLoader.loadClass(ClassLoader.java:289)
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:260)
at java.lang.ClassLoader.loadClass(ClassLoader.java:289)
at java.lang.ClassLoader.loadClass(ClassLoader.java:246)
at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:313)

....and lots of more errors on the call stack.

The machine is an Alpha Cluster system running True64 Unix 5.1B (Patchkit 4). Java is 1.4.2-2

Is this probably a bug in the VM?

Jonathan Woods 08/09/04 12:31:00 AM EDT

Mahesh -

No need for dedicated plug-ins or anything like that. Just run your JBoss instance as normal, except that instead of letting the Java executable be called as it usually would be, make sure it''s invoked using something like the following command line:

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

This just lets Java know that it should run in debugging mode, listening out for debuggers attaching on port 8145 using the JPDA standard. I don''t know much about JBoss, so I don''t know where the Java executable would be called from, but it''s probably in a batch file or script somewhere. You''ll have to edit this - but save a copy of the original.

Once you''ve done this, just run JBoss so that it uses the new command line and then follow Bill''s instructions to connect to it from Eclipse. You''ll need to make sure that the port/address settings you''ve used in the above command line (8145 in this case) match what you set in Eclipse.

Good luck with the presentation.


mahesh adepu 08/08/04 07:38:49 AM EDT

I want to debug my running webapplication from eclipse.
I am using JBoss-3.2.4 as my app. server.I know some plugins
like sysdeo,lomboz.sydeo is for tomcat.lomboz only debugs jsp.so how can i debug on jboss-3.2.4.
I will expect a quick reply.As i have to give presentation on web app. debugging infront of my dev. team.
mahesh adepu

rams 07/02/04 09:52:25 AM EDT

In my project, I am using Tomcat and JBOSS. How do I configure both?
Problem facing
1. After configured the tomcat in the eclipse and while clicking run button it is not refering Jboss which is running in my machine.

Jay 06/21/04 11:03:30 PM EDT

I was able to remotely debug in Tomcat following instructions provided in the following article.


Jeffery Maguire 06/21/04 05:35:35 PM EDT

Hi Bill:

I was struggling to convert my registry in order to berth the APU routers. I was wondering how to change my settings when entering the binary code into my CPU start-up kit. When I try altering the settings, I get a prompt asking for a registry semaphorical access module code. I don''t want to start adjusting my hierarchical routing system, so maybe my algorithm is off. I will keep trying a new encryption method mixed with new IP datagrams. Maybe my meta files are off too due to my Kerberos authentication server problems. If the packet framing is off, can that cause devoiding of path vector protocol??? Anyways, I don''t know if this is the correct path to properly install the debugger so please get back to me. Thank you.

Arthur 06/18/04 11:02:54 AM EDT

I use Windows but dt_socket is also allowed for this OS (see http://java.sun.com/j2se/1.4.2/docs/guide/jpda/conninv.html
for more information). In fact, shared memory causes an error message as I try to connect to a client VM.
I followed your instructions, means, I deleted the war file, started JBoss in debug mode, connected to the client VM from eclipse, copied the war file back again to the deploy directory of JBoss (JBoss deployed it correctly) and hoped to debug the app successfully by starting it - but nothing happend. It''s frustrating.
Question: Should I eventually compile my sources with the debug flag setted. And if so, where can it be set under eclipse?

Bill Dudney 06/16/04 11:06:26 AM EDT

Hi Athur,

What OS are you on? If on Windows you must use shared memory to debug, if you are on one of the Unix plat forms (apple, linux) then the port is for you. Assuming that you are on a Unix box.

From you comments it sounds like you are trying to break in some inialization code. If that is the case make sure you connect the debugger before your app is deployed (i.e. delete the .war from the deploy directory then connect the debugger, then deploy).

Hope this helps. Please post the outcome of your continued work here so that others can benifit.



Athur 06/16/04 05:47:28 AM EDT

Hi Bill,

I followed your instructions to get the JBoss ready for debugging from eclipse. This is my uncommented line in the renamed run.bat from JBoss:

set JAVA_OPTS= -Xdebug -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n %JAVA_OPTS%

A war-file is deployed in the deafault\deploy directory. In eclipse I''m able to connect to "localhost:8787". But starting my webapp the breakpoints aren''t launched.
Did I forget something?

Bill Dudney 06/15/04 07:17:13 AM EDT

Hi Jay, Tomcat does not say anything about the shared memory location during startup. I need more info to help you though, which versioin of Tomcat etc. We should continue this thread via email.

Jay Wang 06/14/04 11:05:36 PM EDT

I am not able to remote debug Tomcat on Windows. I did add dt_shmem.dll into my PATH. But somehow it still doesn''t work. I brought up my Tomcat with catalina.bat jpda start without problems. But I am not sure the Tomcat is listening on port 8000 since the start up log doesn''t say anything about it.

Brian Bezanson 05/25/04 02:34:30 PM EDT

I was going to make the same post as Raj. For $29.95/year buy MyEclipse and debugging is an afterthought. No setup really required -- just select the right radio button in the preferences dialog. MyEclipse is a lot more than just debugging. Check out the new features in version 2.8 at http://www.myeclipseide.com.

Raj Rupani 05/25/04 10:59:10 AM EDT

Brett -- Yeah, I knew the Eclipse debugger was doing the work for java classes under the covers, but what about JSP''s, HTML files, images, basically all non-Java content?

Brett Neumeier 05/25/04 09:55:47 AM EDT

Raj -- it''s really not difficult at all to set this up; the level of detail the article goes into sort of obscures how easy it is. All I do is run "catalina.sh jpda start" from a command line, create a remote debug launcher with default parameters, and I''m off and running. With Java 1.3 and higher, hot code replacement is automatically enabled; if I modify and save a new version of a class, Eclipse rebuilds everything it needs to and injects the new version of the code into the running VM. -bn

Raj Rupani 05/25/04 09:44:34 AM EDT

Overall, this seems like a lot of work to go through with all the plugins available that automate the remote debugging process. The best I''ve found is MyEclipse Enterprise Workbench (www.myeclipseide.com). It has support for all the servers I''ve ever heard of (except Pramati) and source-level JSP debugging. Oh yeah, and as a response to Shiv''s comment, it supports hot code changes of both Java and JSP''s. It''s not free, but at $29.95 it might as well be. I''d spend at least that much money in time setting up the approach in this article by hand.

Bill Dudney 05/25/04 08:50:15 AM EDT

Several people have asked how to make this work on Windows. It appears that you must have JDK_HOME/bin on your PATH so that the the JVM running Eclipse is able to find the dt_shmem.dll. If you do not have ''''shared memory'''' as an option in the ''''Connection Type'''' the missing path entry is likely the problem.

(sorry for the duplace post, some of the markup I put in the first post was kindly deleted for me :-)

Bill Dudney 05/25/04 08:47:42 AM EDT

Several people have asked how to make this work on Windows. It appears that you must have /bin on your PATH so that the the JVM running Eclipse is able to find the dt_shmem.dll. If you do not have ''shared memory'' as an option in the ''Connection Type'' the missing path entry is likely the problem.

Bill Dudney 05/25/04 07:52:36 AM EDT

Hi Pete,

A lot of people agree with you. However I find it very irritating when Eclipse chokes because of an out of memory exception (this happens a lot more often doing Tomcat than WLS of course). if the process is running outside of Eclipse I just kill it and start over. If its in Eclipse I have to shutdown Elcipse and start over.

Fixing problems of the form of ''it works in my dev env, but not in the test'' is another good reason to learn remote debugging. Most often these problems are related to configuration. Given the huge wealth of configuration options it is very hard to track down what is happening without a debugger connection. If your test environment is able to open the port needed to debug the app then you can debug on the test machine to more easily track down the issue.

pete 05/25/04 04:15:53 AM EDT

I find it a lot easier to launch the Application Server''s java Main class in an eclipse launch configuration.

In this way you are just launching say weblogic''s main class e.g ''weblogic.Server'' in eclipse, meaning a socket is not needed to broadcast debugging on. Also the system out messages appear inside eclipse as the application is launched from Eclipse. It''s faster and you can more easily view and save system out content.

You do have to specify the VM_ARGUMENTS -Xdebug -Xrunjdwp:transport=dt_shmem,address=javadebug,suspend=y and also the -D weblogic variables to specify root directory, domain name, bea home, weblogic name but most of these can be copied from the normal startWeblogic.cmd file.

Bill Dudney 05/25/04 12:14:39 AM EDT


The feature is much improved over the 2.1 code base. One of my favorite things is the ''smart'' way that the debugger shows you objects (like HashMaps etc). There are tons of other cool features too.

As far as the hot deploy, I have had some success in hot deploying but not recently. I will investigate and see what I can come up with.

Thanks for the feed back!

Shiv Prakash Ojha 05/24/04 11:59:51 PM EDT

Nice to know an article on remote debugging. This seems to be there in Eclipse for quite long time now and people like me are now using it for last 1.5 to 2 years.

What I am interested in knowing is how can I modify my code in Eclipse while application is deployed and it is hot deployed.

We did this for weblogic sometimes back but somehow after new release of Eclipse 2.1.1 it all ruined.

Here is the Scenario :
We deployed code in Weblogic in exploded form. The target directory for eclispe project was in the weblogic deployed area. We used to start weblogic from Eclipse and it used to provide us the liberty to change code and save in eclipse and it will automatically deployed in the weblogic.

Would like to hear from you more on this type of setup in new version of Eclipse. How it improved then its predecessor.

IoT & Smart Cities Stories
The challenges of aggregating data from consumer-oriented devices, such as wearable technologies and smart thermostats, are fairly well-understood. However, there are a new set of challenges for IoT devices that generate megabytes or gigabytes of data per second. Certainly, the infrastructure will have to change, as those volumes of data will likely overwhelm the available bandwidth for aggregating the data into a central repository. Ochandarena discusses a whole new way to think about your next...
CloudEXPO | DevOpsSUMMIT | DXWorldEXPO are the world's most influential, independent events where Cloud Computing was coined and where technology buyers and vendors meet to experience and discuss the big picture of Digital Transformation and all of the strategies, tactics, and tools they need to realize their goals. Sponsors of DXWorldEXPO | CloudEXPO benefit from unmatched branding, profile building and lead generation opportunities.
DXWorldEXPO LLC announced today that Big Data Federation to Exhibit at the 22nd International CloudEXPO, colocated with DevOpsSUMMIT and DXWorldEXPO, November 12-13, 2018 in New York City. Big Data Federation, Inc. develops and applies artificial intelligence to predict financial and economic events that matter. The company uncovers patterns and precise drivers of performance and outcomes with the aid of machine-learning algorithms, big data, and fundamental analysis. Their products are deployed...
All in Mobile is a place where we continually maximize their impact by fostering understanding, empathy, insights, creativity and joy. They believe that a truly useful and desirable mobile app doesn't need the brightest idea or the most advanced technology. A great product begins with understanding people. It's easy to think that customers will love your app, but can you justify it? They make sure your final app is something that users truly want and need. The only way to do this is by ...
Digital Transformation and Disruption, Amazon Style - What You Can Learn. Chris Kocher is a co-founder of Grey Heron, a management and strategic marketing consulting firm. He has 25+ years in both strategic and hands-on operating experience helping executives and investors build revenues and shareholder value. He has consulted with over 130 companies on innovating with new business models, product strategies and monetization. Chris has held management positions at HP and Symantec in addition to ...
Dynatrace is an application performance management software company with products for the information technology departments and digital business owners of medium and large businesses. Building the Future of Monitoring with Artificial Intelligence. Today we can collect lots and lots of performance data. We build beautiful dashboards and even have fancy query languages to access and transform the data. Still performance data is a secret language only a couple of people understand. The more busine...
Cell networks have the advantage of long-range communications, reaching an estimated 90% of the world. But cell networks such as 2G, 3G and LTE consume lots of power and were designed for connecting people. They are not optimized for low- or battery-powered devices or for IoT applications with infrequently transmitted data. Cell IoT modules that support narrow-band IoT and 4G cell networks will enable cell connectivity, device management, and app enablement for low-power wide-area network IoT. B...
The hierarchical architecture that distributes "compute" within the network specially at the edge can enable new services by harnessing emerging technologies. But Edge-Compute comes at increased cost that needs to be managed and potentially augmented by creative architecture solutions as there will always a catching-up with the capacity demands. Processing power in smartphones has enhanced YoY and there is increasingly spare compute capacity that can be potentially pooled. Uber has successfully ...
SYS-CON Events announced today that CrowdReviews.com has been named “Media Sponsor” of SYS-CON's 22nd International Cloud Expo, which will take place on June 5–7, 2018, at the Javits Center in New York City, NY. CrowdReviews.com is a transparent online platform for determining which products and services are the best based on the opinion of the crowd. The crowd consists of Internet users that have experienced products and services first-hand and have an interest in letting other potential buye...
When talking IoT we often focus on the devices, the sensors, the hardware itself. The new smart appliances, the new smart or self-driving cars (which are amalgamations of many ‘things'). When we are looking at the world of IoT, we should take a step back, look at the big picture. What value are these devices providing. IoT is not about the devices, its about the data consumed and generated. The devices are tools, mechanisms, conduits. This paper discusses the considerations when dealing with the...