[eclipse] Remote debugging Tomcat with Eclipse

I can't seem to debug the tomcat application through Eclipse. I've set

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

and then I run bin/catalina.sh, where I see output saying it's listening for dt_socket on port 8000. But whenever I try to connect to port 8000 in Eclipse (by adding an entry in the remote java application menu), it complains about a refused connect. Any ideas?

This question is related to eclipse tomcat

The answer is

Modify catalina.bat to add

set JPDA_OPTS="-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n" 


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

Optional: Add below line to run the debug mode by default when you run startup.bat

call "%EXECUTABLE%" jpda start %CMD_LINE_ARGS%

Eclipse or STS select debug configuration right click -> new

connection type -> Standard socket Attach
Port -> 8000 (as given in the CATALINA_OPTS)
Host -> localhost or IP address

Just run ./catalina.sh jpda start (forks) or ./catalina.sh jpda run (does not fork, not mentioned in help). All options mentioned here default to sane values.

I was hitting this issue while running Tomcat inside of a Docker container. To fix this make sure you add the '-p 8000:8000' argument in your docker run command to expose this port to your local machine. You will of course need the setenv.sh file in your ${CATALINA_HOME}/bin/ within your container as well.

First of all, if you open catalina.bat with text editor, you see that: "Do not set the variables in this script....." So never change it in that script, instead you can do below steps:

  1. It advices you to create a new bat file with name "setenv.bat".
  2. Then set 2 variables in that bat file such as:

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

    set JPDA_OPTS="-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n"

  3. Lastly run that at cmd that: "catalina.bat jpda start"

  4. In IDE, create remote debug configuration and set host to related server ip and port to 8000.

I spent some time on this to get the right information.

So here is the detailed information step by step.

Environment : Windows 7

TomCat version : 7.0

IDE : Eclipse

Configurations to be added for enabling remote debugging with in tomcat is


I don't recommend above configuration fro non windows environment. To add the above configuration double click on tomcat server which will be available in server view. Find the below screen shot. enter image description here

Now add the above runtime environment configuration to tomcat. For this check below screenshot.

enter image description here

Now got to Arugments tab in Edit launch configuration properties as show in below screen shot.

enter image description here

GoTo VM arguments section add these lines.



enter image description here

Now got to debug button available on eclipse toolbar.

enter image description here

In Debug configurations find "Remote Java Application" and double click on it.enter image description here

In Name field enter any name which you like to.

From project field using browse button select the project which you want to perform remote debug.

The hostname is nothing but the host address. Here i'm working locally so it is "localhost".

Last the Port column the value should be 8000. Apart from Name and Project text fields other two columns Host and port will be filled by eclipse itself if not make you have same values as mentioned. Check Screen shot for info.enter image description here

Now right click on TomcatServer in server console select Add and Remove from context menu. From this dialog you can add the project to server.

Now run the Tomcat sever.

enter image description here

Now run the TomCatDebugConfiguration from Debug Tool.

Last open internal or external browser and run your project. If the execution control reached the break points then the eclipse will prompt for debug perspective.

In tomcat 7, catalina.sh has this code:

if [ "$1" = "jpda" ] ; then
  if [ -z "$JPDA_TRANSPORT" ]; then
  if [ -z "$JPDA_ADDRESS" ]; then
  if [ -z "$JPDA_SUSPEND" ]; then
  if [ -z "$JPDA_OPTS" ]; then

Ii implies that you can setup JPDA with:

export JPDA_TRANSPORT=dt_socket
export JPDA_ADDRESS=8000

Or with:


And finally use:

catalina.sh jpda start


In catalina.bat file please modify the below.

  • Step 1: CATALINA_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"

  • Step 2: JPDA_OPTS="-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n"

  • Step 3: Run Tomcat from command prompt like below: catalina.sh jpda start

  • Step 4: Then in the eclipse create a debug configuration

    1. Give any name for configuration.
    2. Give the project name.
    3. Give the connection type as Standard(Socket Attach)
    4. host as localhost
    5. port as 8000( or any port number , but that should be same in other places also).

See this answer for issues I had with Java 8 and Tomcat 9: Java remote debugging (JPDA) not working for me in Tomcat 9

This is similar to @DAB's warning, and his solution is likely more secure.

Many of the above answers are correct, but remember that by default the debugger will listen on localhost, which means you can debug only if you're running the debugging client (for example, the IDE) on the same machine.

If you are debugging a remote server you will need to specify the correct IP address on that server to listen on, for example


catalina.sh jpda start

Note that the address is now

Of course, you can also check which IP is actually being used, by running

netstat -an

This command is valid on both windows and Linux - you just need to filter out the port with find (Windows) or grep (Linux).

Modifying the startup.bat with the CATALINA_OPTS AND JPDA_OPTS didn't work for me but adding them to catalina.bat did

  1. Modify catalina.bat

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


  1. Modify startup.bat to include jpda

change call "%EXECUTABLE%" start %CMD_LINE_ARGS% to

call "%EXECUTABLE%" jpda start %CMD_LINE_ARGS%

Then configure remote java application in your debug configurations in Eclipse.

In the tomcat bin directory wherecatalina.bat or .sh is found (aka {CATALINA_BASE}/bin), edit (create if not there):


Add the following line:

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

That's all you need to do, you don't need to edit the catalina.bat (or .sh) file.

See the comments in catalina.bator catalina.sh.

You may have to adjust the syntax for your particular environment/situation. For example, if you already have CATALINA_OPTS defined, you might do something like this (in a windows environment):

set CATALINA_OPTS=%CATALINA_OPTS% -Xdebug -Xrunjdwp:transport=dt_socket,address=8088,server=y,suspend=n

To debug from Eclipse:

run->Debug configurations...->Remote Java Application->New

and specify a name, the project you are debugging, and the tomcat host and debug port specified above.

For apache-tomcat-8.5.28 version just do this,

catalina.bat jpda start

As the default settings already configured for us in catalina.bat as

if not "%JPDA_OPTS%" == "" goto gotJpdaOpts set JPDA_OPTS=-agentlib:jdwp=transport=%JPDA_TRANSPORT%,address=%JPDA_ADDRESS%,server=y,suspend=%JPDA_SUSPEND%

So no need of any other config. And when you execute command catalina.bat jpda start, you can see debug port 8000 is opened.

For apache-tomcat-8.5.28

modify JDPA_OPTS like the below then run like catalina.bat jpda start


Let me share the simple way to enable the remote debugging mode in tomcat7 with eclipse (Windows).

Step 1: open bin/startup.bat file
Step 2: add the below lines for debugging with JDPA option (it should starting line of the file )

    set JPDA_ADDRESS=8000  
    set JPDA_TRANSPORT=dt_socket  

Step 3: in the same file .. go to end of the file modify this line -

    call "%EXECUTABLE%" jpda start %CMD_LINE_ARGS%  
    instead of line  
    call "%EXECUTABLE%" start %CMD_LINE_ARGS%  

step 4: then just run bin>startup.bat (so now your tomcat server ran in remote mode with port 8000).

step 5: after that lets connect your source project by eclipse IDE with remote client.

step6: In the Eclipse IDE go to "debug Configuration"

step7:click "remote java application" and on that click "New"

step8. in the "connect" tab set the parameter value

   project= your source project  
   connection Type: standard (socket attached)   
   host: localhost  

step9: click apply and debug.

so finally your eclipse remote client is connected with the running tomcat server (debug mode).

Hope this approach might be help you.


If still all the above doen't work you can always add to the script

    set "JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"

Examples related to eclipse

How do I get the command-line for an Eclipse run configuration? My eclipse won't open, i download the bundle pack it keeps saying error log strange error in my Animation Drawable How to uninstall Eclipse? How to resolve Unable to load authentication plugin 'caching_sha2_password' issue Class has been compiled by a more recent version of the Java Environment Eclipse No tests found using JUnit 5 caused by NoClassDefFoundError for LauncherFactory How to downgrade Java from 9 to 8 on a MACOS. Eclipse is not running with Java 9 "The POM for ... is missing, no dependency information available" even though it exists in Maven Repository The origin server did not find a current representation for the target resource or is not willing to disclose that one exists. on deploying to tomcat

Examples related to tomcat

Jersey stopped working with InjectionManagerFactory not found The origin server did not find a current representation for the target resource or is not willing to disclose that one exists. on deploying to tomcat Spring boot: Unable to start embedded Tomcat servlet container Tomcat 404 error: The origin server did not find a current representation for the target resource or is not willing to disclose that one exists Spring Boot application in eclipse, the Tomcat connector configured to listen on port XXXX failed to start Kill tomcat service running on any port, Windows Tomcat 8 is not able to handle get request with '|' in query parameters? 8080 port already taken issue when trying to redeploy project from Spring Tool Suite IDE 403 Access Denied on Tomcat 8 Manager App without prompting for user/password Difference between Xms and Xmx and XX:MaxPermSize