Difference between revisions of "Troubleshooting"

(OutOfMemoryError: Tweak paragraph order)
(The fallback way)
Line 70: Line 70:
     <li>[[File:Win.png|x20px]] On Windows:
     <li>[[File:Win.png|x20px]] On Windows:
         <li>Press {{key|Ctrl|Pause}} in the Command Prompt window to print the stack trace.</li>
         <li>Press {{key|Ctrl|Pause}} in the Command Prompt window to print the stack trace. ('''Note:''' this shortcut actually uses the [[Wikipedia:Break_key|Break key]])</li>
         <li>Click the Command Prompt icon in the upper left corner of the window, and choose {{bc|Edit|Mark}}.</li>
         <li>Click the Command Prompt icon in the upper left corner of the window, and choose {{bc|Edit|Mark}}.</li>
         <li>Select the stack trace by dragging with the left mouse button.</li>
         <li>Select the stack trace by dragging with the left mouse button.</li>

Revision as of 12:34, 7 December 2015


How to troubleshoot problems

Checking the Java version

You can tell which Java version ImageJ is using by clicking the ImageJ status bar and looking for the part that says e.g. "Java 1.8.0_45 [64-bit]". The relevant number is the one after "Java 1."—so e.g. "Java 1.8.0_45" or similar indicates Java 8, while "Java 1.7.0_79" or similar indicates Java 7.

On OS X, you can use this script to diagnose which versions of Java are installed on your system.

See also How do I launch ImageJ with a different version of Java?.

Launching ImageJ from the console

To diagnose problems with ImageJ, it is often helpful to launch it in debug mode. There are several ways:

  1. Launch with the --debug flag.
    • On Linux 64-bit (from a console):
      $HOME/ImageJ.app/ImageJ-linux64 --debug
    • On OS X (from Terminal):
      /Applications/ImageJ.app/Contents/MacOS/ImageJ-macosx --debug
    • On Windows 64-bit (from Command Prompt):
      %HOMEPATH%\ImageJ.app\ImageJ-win64.exe --debug
  2. Set the DEBUG environment variable. E.g., on Linux:
    DEBUG=1 $HOME/ImageJ.app/ImageJ-linux64
  3. Rename the launcher. You can rename the executable from ImageJ-xxx to debug (debug.exe on Windows) before launching, and the launcher will be more verbose about what it is doing.
  4. Set scijava.log.level. You can control the log level more precisely by setting the scijava.log.level system property. E.g., on Linux:
    $HOME/ImageJ.app/ImageJ-linux64 -Dscijava.log.level=trace --

    Valid levels include: none, error, warn, info, debug and trace. See the Logging page for more about SciJava logging.

The other debug mode

There is another debug mode, which can be enabled in the Edit  › Options  › Misc... menu, by checking Debug mode. This might reveal different information than using the techniques described above. For maximum debugitude, turn on both!

If ImageJ freezes or hangs

If ImageJ appears to hang—i.e., it stops responding to inputs—it is often helpful to take a "snapshot" of where the program is at after the hang occurs. This information can give the developers valuable hints about how to fix the problem.

There are two ways to create such a snapshot, known as a "thread dump" or "stack trace".

The easy way

  1. Press Shift+\ in ImageJ itself. If successful, it will open a new window with the stack trace.
  2. Press ^ Ctrl+A to select it, then ^ Ctrl+C to copy it to the clipboard.

The fallback way

If the first method does not work, and you can reproduce the hang:

  1. Launch ImageJ again, this time from the console as described above.
    • Win.png On Windows, you will need to download and run this batch file, which launches ImageJ with an attached Command Prompt window.
  2. Generate and copy the stack trace:
    • Osx.png Tux.png On non-Windows platforms:
      1. Press ^ Ctrl+\ in the console window to print the stack trace.
      2. Select the stack trace by dragging with the left mouse button.
      3. Right click and select "Copy" to copy it to the clipboard.
    • Win.png On Windows:
      1. Press ^ Ctrl+ Pause in the Command Prompt window to print the stack trace. (Note: this shortcut actually uses the Break key)
      2. Click the Command Prompt icon in the upper left corner of the window, and choose Edit › Mark.
      3. Select the stack trace by dragging with the left mouse button.
      4. Press Enter to copy it to the clipboard.

Once you have the stack trace. you can paste it into a bug report!

If ImageJ crashes

If ImageJ crashes—i.e., the program suddenly terminates, with or without an error message—it is very helpful to identify the steps which can reliably reproduce the crash:

  • Launch ImageJ from the console as described above.
  • Perform the same actions which previously resulted in the crash.
  • Take note of any error messages in the console window, which you can copy and paste it into a bug report.

If ImageJ does not start up

If the ImageJ window never appears after launching the program, the installation may be corrupted. While the developers of ImageJ make a serious effort to prevent this problem from happening, it is still possible after running the Help  › Update... command, due to bugs in the Updater.

The easiest workaround is to download a fresh copy of the software.

If you are feeling investigative, you can try launching ImageJ from the console to get more information about why it is failing to start up. After doing that, you will probably see some information printed to the console, which you can paste online to somewhere like Pastebin.com, and write to the Community to ask for help deciphering it.

Advanced debugging techniques

If you are technically savvy, check out the Debugging page for additional—but more complicated—debugging techniques.

Common issues

The image I loaded is displayed all black! But it is not black!

This problem usually arises when 12-bit or 14-bit images are loaded into ImageJ without autoscaling. In that case, they are treated as if they were 16-bit images, and therefore the dynamic range is all wrong. You can fix this by clicking on Image  › Adjust  › Brightness/Contrast... and hitting the Auto button.

The image colors do not match what I see in other programs! ImageJ is wrong!

In many cases, ImageJ performs autoscaling by default, to improve the contrast of your image. Otherwise, in many cases with scientific images you might see only a black square (see previous question).

You can override the autoscaling using the Brightness/Contrast dialog.

It is important to understand that your image is a collection of samples, each of which has a numerical intensity value. The unit of these values is rather arbitrary and unspecified, depending on the type and calibration of your detector. Your file is stored with a certain bit depth, meaning these intensities can range from 0 (no light detected) to a particular maximum value (the most light the detector is capable of detecting). For example, 8-bit images have a maximum value of 255, whereas 16-bit images have a maximum of 65535. In practice though, especially with higher bit depths, your detector will not typically record sample intensities across that entire range of values (and if it does record a significant number of values at the maximum, you probably oversaturated your detector, which will skew your analysis!).

Because the full range of values is typically much less than the maximum—e.g., in the case of a 12-bit detector the actual maximum range is 0-4095, and often even smaller in practice—ImageJ performs autoscaling to show you a meaningful or "pretty good" image by default, which is not just a black square (see previous question). That is: it maps the darkest actual intensity in your data to black, and the brightest actual intensity in your data to white. You can override this mapping using the Brightness/Contrast dialog under the Image  › Adjust menu (shortcut: Shift+C).

Alternately, to disable autoscaling during initial import, you can use the Bio-Formats plugin to import your data with the "Autoscale" option turned off:

  • File  › Import  › Bio-Formats
  • Choose your file
  • Uncheck the "Autoscale" box
  • Click OK
  • The data will be scaled to match the maximum of the bit depth, rather than autoscaled.

Further reading:

The same plugin gives different results on different machines!

While ImageJ strives for reproducible analysis, there are many reasons results can differ. Check the following:

  • Ensure that the version of ImageJ is exactly the same on both machines.
  • Ensure that the options of ImageJ match between the machines.
    • A fast way to ensure this is the Edit  › Options  › Reset... command, which resets everything to its default state.
    • Alternately, you can check the settings in the following dialog boxes:
      • All Edit  › Options dialog boxes
    • Process  › Binary  › Options... – a very common culprit of black-vs.-white issues is the "Black background" option.
    • Process  › FFT  › FFT Options...
    • Image  › Overlay  › Overlay Options...
    • Analyze  › Gels  › Gel Analyzer Options...
    • Press L for the Command Finder and type "options" and double check any other options you think might be relevant.
  • If you are running your analysis headless, there might be a bug in the headless support.
    • Try the analysis headless on both machines and see if the results match.
    • Try the analysis headless vs. through the GUI on a single machine, and see if the results match.
    • If the results differ due to headlessness, it is a bug—please report it!

Common error messages


Why does ImageJ not release any memory back to the system?

This is a characteristic of the Java runtime. In many cases, Java never releases memory back to the system, so memory monitors such as Windows Task Manager will always report an ever-growing amount of RAM used by the Java process, until the JVM shuts down.

The best way to monitor ImageJ's actual memory usage is to run the Monitor Memory... command. You can also click on the ImageJ status bar to trigger a garbage collection operation, which will typically decrease the memory use.

That said, some articles suggest that you can cause Java to give back free memory to the OS under certain conditions; see:

To be clear, Java does reuse memory when you close and reopen images. The behavior described above is not a memory leak per se. It should be possible to leave ImageJ running for days or weeks at a time doing batch processing and it have it work just fine.

See also:

The error means ImageJ ran out of available computer memory (not hard drive space).

The first thing to do is make sure that ImageJ has a large enough "maximum heap" size:

  • Edit  › Options  › Memory & Threads
  • Change "Maximum Memory" to something larger (at most, 1000 MB less than your computer's total RAM).
  • Restart ImageJ for the new memory settings to take effect.

Note that in most cases, the ImageJ launcher will make an initial guess at a reasonable value: ~75% of physical RAM.

You can confirm how much memory is actually available by clicking on the status bar. You will see a "[used] of [max]" memory message, as pictured here:


If you are already at the limits of your computer's physical memory, the next step would be to add more.

If setting this value somehow has no effect: Check for an environment variable called _JAVA_OPTIONS or similar, which is overriding the value. If the variable exists, change the memory value there, or remove the variable completely.

About Java garbage collection: Java always automatically calls the garbage collector when the heap is getting full [1]. While it is possible to manually invoke the garbage collector by clicking ImageJ's status bar—or programmatically by calling run("Collect Garbage") in a macro or System.gc() in a plugin—it will not solve the fundamental problem of Java actually not having a sufficient amount of memory. (The only exception to this is a rare case where Java decides that garbage collection is happening too slowly, in which case you should see the message "GC overhead limit exceeded" [2]).


This error usually means that your image planes are larger than the maximum supported size.

ImageJ1 only supports image planes with 2 gigapixels or less. If your data has extremely large image planes—e.g., 50000 x 50000 pixels—you may need to analyze region by region. One way to do this is using the "Crop on import" feature of the Bio-Formats plugin.

ImageJ2 supports larger image planes internally, but uses the ImageJ1 user interface by default, which once again limits visualization to 2 gigapixels. The ImageJ2 team is working to lift these size restrictions; see imagej/imagej#87.


Usually, this error takes the form of "Unsupported major.minor version 52.0" or similar, and indicates you are attempting to use a plugin which requires a newer version of Java than you are running. For example, you may have enabled an update site that requires Java 7, but your ImageJ is using Java 6.

Check which version of Java is being used by ImageJ; see Checking the Java version above.

The number given in the UnsupportedClassVersionError error messages is an internal code, which translates to Java versions as follows:

Internal code Java version
45.0 JDK 1.1
46.0 J2SE 1.2
47.0 J2SE 1.3
48.0 J2SE 1.4
49.0 J2SE 5.0
50.0 Java SE 6
51.0 Java SE 7
52.0 Java SE 8

See Java version history for more information about these different versions.

To control the version of Java that ImageJ uses, see How do I launch ImageJ with a different version of Java.

NoSuchMethodError or NoClassDefFoundError

These errors indicate a "version skew" between the software libraries in your ImageJ installation. Most commonly, this situation occurs when multiple update sites are enabled which ship incompatible versions of those libraries.

The proper fix is for the maintainers of those update sites to reconcile the versions somehow, but as a user you can work around the issue in the meantime by disabling the problematic update site(s). Start from a fresh download of ImageJ, enabling the update sites you want one by one, testing your workflow each time. Once you determine which update site(s) causes the issue, you can create a separate copy of ImageJ with only the problematic site(s) enabled. Although you will no longer have a single ImageJ with all desired functionality enabled, keeping isolated installations will let you continue using all the plugins you need by launching each appropriate copy of ImageJ.

OS X issues

Why does ImageJ run so slowly?

Java painting bug

On OS X, older versions of Java 8 (prior to 1.8.0_45)—as well as all versions of Java 7 (including 1.7.0_80)—are extremely slow at displaying images. You should either upgrade to the latest version of Java 8, or revert to Java 6.

App Nap

On recent versions of OS X—10.9 "Mavericks" and later—there is an "App Nap" feature which dramatically slows down applications that are not in the foreground. Leave ImageJ in the foreground while it is processing to avoid this issue. (There are also various ways to disable App Nap on your machine, but we have not had much success with them. If you find a solution that works, allowing ImageJ to run fast in the background, please tell us on the forum!)