How to report a deadlock

Say you've encountered a problem in Eclipse that has one of the following symptoms:

• A long pause where the GUI does not redraw or respond
• A deadlock or freeze where the GUI stops responding indefinitely
• CPU pegged at 100% indefinitely
• A modal dialog that won't close

In all of these cases, you should report a new bug. See FAQ How do I report a bug? for more information on reporting bugs. Include the following information in the report:

1. What build of Eclipse you are using (see Help > About)
2. What VM you are using (version and vendor). Use "java -version" to find out version information.
3. What you were doing at the time of the deadlock (what dialog, wizard, editor, etc)
4. Your JVM configuration: how much memory is being allocated to the JVM
5. Your machine configuration: how much RAM, how much RAM is free, was it swapping
6. Whether it is reproducible; if so, provide steps
7. Once the bug report is created, attach a stack trace (also known as thread dump), using the "Create a New Attachment" link in bugzilla.

Regardless of how you get your stack trace, please paste the contents into a file and then attach the file. Stack traces pasted directly into bugzilla look very ugly. On an IBM VM, the stack trace is written to a file in the working directory of the Java process. Typically this will be found in the eclipse install directory. The steps for producing a stack trace vary according to what operating system you are using.

Recommended Method for getting the thread dump:

When you can run Eclipse with a recent Sun Java 6 or higher JVM, using the jvisualvm method is recommended, since it is easy and allows generating a heap dump at the same time. In general, it is helpful to always run Eclipse as

  eclipse -vm /path/to/jdk16/bin/java -vmargs -XX:+HeapDumpOnOutOfMemoryError

See MemoryAnalyzer#Getting_a_Heap_Dump for more details about heap dumps, which help diagnosing out of memory errors. The heap dump will be large (up to 200 MB compressed), but very helpful diagnosing the issue.

See below for other methods acquiring a thread dump (aka stack trace).

Getting a stack trace on Windows

Using jvisualvm

The Java Visual VM tool is shipped as part of JDK 1.6.0_07 or later. It can create thread dumps of programs run with Java6. Programs run with Java5 can also be dumped when they have been started with the -Dcom.sun.management.jmxremote system property. This is best added as a separate line in eclipse.ini anywhere after the -vmargs argument:

-vmargs
-Xms40m
-Xmx384m
-Dcom.sun.management.jmxremote

'The jvisualvm output is better than in the Java5 jconsole tool, so when you have Java6 this is now the preferred method.

1. Launch the JDK's jvisualvm tool.
2. Connect to Eclipse by double clicking the process.
3. Switch to the Threads tab.
4. Click the "Thread Dump" button in upper right.

Using the Adaptj StackTrace tool

This is the preferred method when Java 6 is not available.

Note: As of now, the URL specified below is not accessible and it's not known whether this will be available anytime soon. Therefore, it is recommended to use any of the other given methods.

Given that your Eclipse is currently hanging in a deadlock, best use the tool found at the adaptj home page, since it requires no preparations:

• Follow the link and select button "Launch" (press "OK" to "Run as a Java WebStart Application")
• Select menu Process > Select
• In the combo box "Process ID" press the "..." button, select "eclipse.exe" application and click OK
• Pick menu Process > Thread Dump
• File > Save As (enter some name e.g. C:\myThreadDump.txt)

Take Care: The generated thread dump also contains the JVM's environment including the commandline that was used for starting Eclipse. Take care not to expose any sensitive information (like keyring password) before giving outsiders access to your file.

Attach that file on bugzilla when filing a bug that describes how you got the deadlock.

Using eclipse -consolelog

As an alternative, if you are interested in reporting bugs, it is useful to always run with a console open so you can obtain stack traces. If you are using Eclipse 3.3 (Europa) or greater on Windows, you can simply run with eclipsec.exe to obtain a console window. On Eclipse 3.2 or older, you will need to specify java.exe as your VM on the command line. Here is a typical command line for starting Eclipse using java.exe:

  eclipse -vm c:\jre\bin\java.exe -vmargs -Xmx300M

Or, if you normally use your system's default java VM, you can use

  eclipse -consolelog

or, even

  eclipse -consolelog -debug

Once you have a Java console window, you can obtain a stack trace by simply hitting Ctrl+Break when the console window is active.

Note: its recommended you increase the "buffering size" of the console window, to a wide width such as 300 (default is usually 80) and perhaps even a long length (such as 3000) so there's plenty of room for a well formatted stack trace. Then, preferably, copy/paste the stack trace to a text file and attach it to a bugzilla, so its formatting is preserved.

Debugging as an Eclipse Application

The same is possible if you start Eclipse using the "Eclipse Application" launch configuration (ie. from another instance of Eclipse). The problem here is that you don't have a console in which to press Ctrl+Break. You will need a tool like [SendSignal].

SendSignal can send a break to any process and you will get the stack dump in the Eclipse console of the controlling instance. This has the additional advantage that the buffer will probably be big enough. The tool needs the PID (process id) which is not that simple to find on Windows. Either you use a tool like [Process Explorer]. There, you can see the right process as a child of your Eclipse process.

If you can't do this, you'll have to use the Windows Task Manager. The first step is to make the PID visible. Select the "Process" tab and then "Select columns..." in the View menu. Make sure PID is selected. To determine which PID is the one you're looking for, sort the processes by name and watch the running Java processes (javaw.exe). Look again after you started the Eclipse process. There should be a new process, now.

Note: It doesn't do much harm if you send the signal to the wrong, process. You just won't see the thread dump.

Getting a stack trace on other platforms

This applies to Unix, Linux, and Mac OS X systems.

Using jvisualvm (Java 6)

When you can run Eclipse with a Java 6 JVM, this is the preferred method.

See the Windows Instructions above for how to use it.

Using kill -3 (UNIX only)

On all Unix-based platforms, the steps for producing a stack dump are the same:

1. Use the "ps" or the "jps" command to find out the process id (pid) of the Java VM
2. Invoke "kill -3 <pid>" where <pid> is the process id of the Java VM

A thread dump will be printed on the console where you started Eclipse. Since it may be long, in order to Copy & Paste it, it might be necessary to scroll and/or reduce the font size (xterm: right-click > font size > unreadable).

Using jconsole (requires JDK 1.5 or later)

This works on any OS, provided that the debuggee (Eclipse) has been launched with

  eclipse -vmargs -Dcom.sun.management.jmxremote

which is a non-intrusive, recommended argument for any Eclipse based program in order to facilitate diagnostics.

• Launch the JDK's jconsole tool from commandline. You can attach to the Java Process and inspect / copy the backtrace of any interesting Thread separately
• This allows introspection to any single Thread, but not getting a complete backtrace; the "Detect Deadlock" functionality works rarely

Using jps / jstack (requires JDK 1.6 or later)

• On command line, use jps -v to find the PIDs of Java processes and jstack <pid> to show the stack trace of Java processes.
• Supported starting JDK 5 for UNIX / JDK 6 for Windows

Example session:

$ jps -v
32308 org.eclipse.equinox.launcher_1.5.0.v20180119-0753.jar -Dosgi.requiredJavaVersion=1.8 -Dosgi.instance.area.default=@user.home/eclipse-workspace -XX:+UseG1GC -XX:+UseStringDeduplication -Dosgi.requiredJavaVersion=1.8 -Dosgi.dataAreaRequiresExplicitInit=true -Xms256m -Xmx1024m -Dswt.dbus.init
8824 Jps -Dapplication.home=/usr/lib/jvm/java-8-oracle -Xms8m
$ jstack 32308 > /tmp/jstack.txt

Here 32308 and 8824 are PIDs of Java processes. 8824 is jps itself and is of no interest for us. 32308 is and Eclipse process judging from presence of org.eclipse.equinox.launcher in its command line. Jstack command saves stack trace of Eclipse process in a file /tmp/jstack.txt, attach the file to bug report.

jstackSeries -- jstack sampling in fixed time intervals (tested on Linux)

This simple shell script takes several jstack snapshots in fixed time intervals:

#!/bin/bash

if [ $# -eq 0 ]; then
    echo >&2 "Usage: jstackSeries <pid> [ <count> [ <delay> ] ]"
    echo >&2 "    Defaults: count = 10, delay = 1 (seconds)"
    exit 1
fi

pid=$1          # required
count=${2:-10}  # defaults to 10 times
delay=${3:-1} # defaults to 1 second

while [ $count -gt 0 ]
do
    jstack $pid >jstack.$pid.$(date +%H%M%S.%N)
    sleep $delay
    let count--
    echo -n "."
done

If your "sleep" command supports fractions of seconds by providing a floating point value, e.g. "0.1" you may sample e.g. every half second using

jstackSeries <pid> 10 0.5

To compare the results you may use interactive diff viewers, e.g.

vimdiff file1 file2 file3 file4 # up to 4 files
kdiff3 file1 file2 file3
...

Another way to see what parts of the jstack trace are changing over time is to compare adjacent jstack trace using context diff (-c option):

d_old=""
for d in jstack.13585.12171*
do 
  if [ -n "$d_old" ]
  then
    diff -c "$d_old" "$d"
  fi
  d_old="$d"
done

Here, the result shows only the places where the jstack trace changes from file to file.

Remote Diagnosis

If you want to get a Thread Dump from Eclipse in a situation where some UI interaction is required, you'll need a separate machine for making the Thread dump: on the "target" machine, use Eclipse like you normally would (e.g. open a context menu) and from the "debug" machine initiate the Thread dump.

On UNIX machines, the "kill -3" method will work from remote logins as well; on Windows machines, if you have some tool to log in remotely, you can use SendSignal in a similar way, or you use the jps/jstack method if you have JDK 1.6 or later. Remote login to Windows works with Eclipse RSE through a Windows DStore Daemon, for instance. Alternatives are setting up an sshd or telnetd with Cygwin or Microsoft SFU.

Remote Debug Connection

Recommended Method if you can afford starting with -Xdebug and reproduce your issue with -Xdebug

• On target machine, launch
  eclipse -vmargs -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005
• On debug machine, launch Eclipse, create a new Debug Launch of type "Remote Java Application" and enter the hostname / port number (5005)
• On remote debug session, suspend VM at the time you want the thread dump
• In debug view, expand all interesting stack frames, select all, right-click > Copy Stack

jconsole remote connection (requires JDK 1.5 or later)

• On target machine, launch
  eclipse -vmargs -Dcom.sun.management.jmxremote.port=12345 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false
• On debug machine, launch jconsole, connect to remote hostname:12345
• Use different port number if 12345 is taken
• This allows introspection to any single Thread, but not getting a complete backtrace; the "Detect Deadlock" functionality works rarely

jstack remote (UNIX only, requires JDK 1.5 or later)

• On target machine, launch jsadebugd
• On debug machine, launch jstack with appropriate parameters for remote target

Other options

For yet other options to get a thread dump, see Mylyn Contributor Reference#Debugging

For diagnosing and getting stack traces for deadlocks using the Eclipse debugger see Deadlock detection with Eclipse