This guide describes how to troubleshoot issues while working with the library.

Unexpected Behavior

If JxBrowser behaves unexpectedly, please try reproducing the same behavior in Google Chrome and see if it persists. Very often the behavior is expected and this is just how the library works.

If you see that the same functionality works in Google Chrome, then please provide us with the details of the issue, the details of the environment where the issue is reproducible, and steps to reproduce it.

Video Does Not Play

Format of the video you are trying to play might not be supported by JxBrowser. Please check the list of supported video and audio formats.

If one of supported video formats does not play please report an issue.

Startup Failure on Windows

If JxBrowser fails to start in your Windows environment, please perform the following actions:

  1. Make sure that your environment meets the system requirements for Windows.
  2. Configure your antivirus software to allow JxBrowser to run its executable programs. JxBrowser runs Chromium in a separate native process. Sometimes it fails to launch the native process due to the installed antivirus software or due to local security policy. Even though all JxBrowser executable files are signed with a valid and trusted signature, some antivirus software may still not allow running programs that are not in their whitelist.

If the actions above do not help, please enable logging, reproduce the issue, and provide us with the collected log messages.

Startup Failure on Linux

If JxBrowser fails to start in your Linux environment, please perform the following actions:

  1. Make sure that your environment meets the system requirements for Linux.
  2. In some Linux distributions JxBrowser fails to run Chromium process because it cannot find the required system libraries. In such case it prints the missing library names in the log messages. To resolve this issue please enable logging, get the list of missing system libraries, and install them.

If the actions above do not help, please enable logging, reproduce the issue, and provide us with the collected log messages and the with the name and version of your Linux distribution.

Slow Startup on Windows

JxBrowser startup consists of many actions. If JxBrowser runs in the environment for the first time, it extracts Chromium binaries into a predefined directory. If the binaries are compatible with this version of JxBrowser, it runs the Chromium Main process and sets up the IPC connection between Java and the Chromium Main process.

The startup time depends on the environment, the hardware performance, and the installed antivirus software.

For example, if you run JxBrowser for the first time on Windows 10 64-bit without antivirus software, on the i7/16GB RAM/512GB SSD hardware, the startup time would be ~2-3 seconds. Every next run will take ~1 second because Chromium binaries are already extracted, so JxBrowser will not extract them again.

If you see that JxBrowser startup is really slow in your Windows environment with antivirus software, please try disabling your antivirus and see if it helps.

If it does not help, please enable logging, reproduce the issue, and provide us with the collected log messages and the details about your hardware.

Unresponsive Java Application

If your Java application hangs and you believe it happens because of JxBrowser, please enable logging, reproduce the issue, take a thread dump when the application hangs, and provide us with the collected thread dump and the log messages.

Taking Thread Dump from JVM

1. Get the PID of your Java process

To obtain a thread dump you will first need to get your Java process’ PID.

To find the PID on Linux and macOS use the following command line:

ps -el | grep java

On Windows press Ctrl+Shift+Esc to open the task manager and find the PID of the Java process.

2. Request a thread dump from the JVM

If installed/available, we recommend using the jstack tool. It prints thread dumps to the command line console.

To obtain a thread dump using jstack, run the following command:

jstack -l <pid>

You can output consecutive thread dumps to a file using the console output redirect/append directive:

jstack -l <pid> >> threaddumps.log

Unexpected Chromium Process Termination

JxBrowser runs Chromium in a separate native process. An error in the Chromium engine might lead to unexpected process termination. The information about the native crash is stored in a crash dump file.

If Chromium process is unexpectedly terminated and you received the Engine Crashed event, please report the issue and share the generated crash dump file using an online file sharing service such as Dropbox, Google Drive, etc.

Collecting Crash Dumps


By default crash dump file generation is enabled on Windows. In case of an unexpected Chromium process termination JxBrowser generates a crash dump file and stores it in the %localappdata%\JxBrowser directory.

To change the default directory please use the jxbrowser.crash.dmp.dir System Property. For example:

System.setProperty("jxbrowser.crash.dump.dir", "C:\\.jxbrowser\\crash-dumps");


In case of an unexpected Chromium process termination on macOS the crash dump file (*.crash) with all necessary information is automatically generated and stored in the /Users/<username>/Library/Logs/DiagnosticReports/ directory.

You can also find the generated crash dump files in the Console application:



On Linux platforms crash dumps are not generated by default. To enable crash dump file generation you need to configure your Linux environment accordingly.

To enable crash dump files generation on Ubuntu please modify the /proc/sys/kernel/core_pattern file via the following command:

$ echo '/tmp/core.%e.%p.%t' > /proc/sys/kernel/core_pattern

It will change a path for the crash dump files, so those files would have names with the /tmp/ pattern. You must also change the quota for storing dump files with the following command:

$ ulimit -c unlimited

After reboot all the changes will be reverted to default. To prevent this you need to edit the /etc/sysctl.conf file and set the kernel.core_pattern parameter to the required value. For example, in the /etc/sysctl.conf file put/modify the following property:

kernel.core_pattern = /tmp/core.%e.%p.%t

To enable crash dump files generation on the operating system startup you must add the following line to /etc/profile:

ulimit -c unlimited

When a crash happens in the Chromium engine, the core dump file will be generated and saved in the /tmp directory with the core.%e.%p.%t name.


The root cause of many issues can be detected by analyzing JxBrowser log messages.

If you see an issue or some unexpected behavior, please configure JxBrowser to print all log messages to a file or System.err, reproduce the issue, and provide us with the collected log messages.

By default JxBrowser is configured to print all log messages with the ERROR level to System.err.


JxBrowser supports the following logging levels: DEBUG < INFO < WARNING < ERROR. By default only log entries with the logging level ERROR are output and all other log entries are ignored.

In addition there is a level OFF that can be used to turn off logging, and a level ALL that can be used to enable logging of all messages.

You can change the default logging level via the jxbrowser.logging.level system property or JxBrowser Logging API.

Example: Setting Logging Level

To print ALL log messages with the logging level DEBUG and higher please use the following Java VM argument:


Or set the system property in the source code:

System.setProperty("jxbrowser.logging.level", "ALL");

You can also set the required logging level using JxBrowser Logging API:

import com.teamdev.jxbrowser.logging.Level;
import com.teamdev.jxbrowser.logging.Logger;

Logging to a File

To print all log messages to a file please use the jxbrowser.logging.file system property.

You can set the property via the following Java VM argument:


Or in the source code:

System.setProperty("jxbrowser.logging.file", "jxbrowser.log");

The value of the property represents an absolute or relative path to a file where the log messages will be printed.

If the log file cannot be created for some reasons, the library will use the default behavior and print an error message with the exception stack trace to System.err. It will help you to determine why the library failed to create the log file.

Overlapping JMenu

When you embed BrowserView component configured to use the Hardware Accelerated rendering mode into Java Swing frame with menu bar, you can see that the component overlays pop-up menu as shown on the following screenshot:

JMenuBar Overlapping Issue

The reason of this issue is in mixing lightweight pop-up menu and the heavyweight BrowserView component used in the hardware accelerated rendering mode. To fix this issue you need to disable the lightweight implementation of the Swing pop-ups using the following command:


This code forces all Swing pop-up menus to become heavyweight. As result, you do not see the issue anymore:


IllegalAccessException in OpenJFX

When you run your JavaFX application with the embedded BrowserView under OpenJFX and the Hardware Accelerated rendering mode is used you can notice that the browser content is displayed in the top left desktop corner as shown below:

IllegalAccessException in OpenJFX issue

and the IllegalAccessException with the following message is thrown:

class com.teamdev.jxbrowser.internal.util.ReflectionUtil cannot access class 
    com.sun.javafx.stage.WindowHelper (in module because module does not export com.sun.javafx.stage to unnamed module

The described exception can also be observed in the same case when the Off-Screen rendering mode is used.

The reason is that the modules that needs to be downloaded separately are not included into the module path. Since JavaFX is no longer a part of JDK in Java 11 these modules do not belong to the “system JDK modules”. That is the reason the default rules related to exporting packages to unnamed modules and reflective access to these packages do not apply to them.

In order to run JxBrowser under OpenJFX the following VM parameters must be applied at runtime:

--add-exports javafx.controls/com.sun.javafx.scene.control=ALL-UNNAMED
--add-exports java.desktop/sun.awt=ALL-UNNAMED
Go Top