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. Enable logging and take a look at the log messages.

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. For example:

java.lang.UnsatisfiedLinkError: /tmp/JxBrowser/VERSION/ cannot open shared object file: No such file or directory

To resolve the issue with missing system libraries you just need to install them.

If it does 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

The crash dump file generation is enabled by default on all supported platforms. In case of an unexpected Chromium process termination JxBrowser generates a crash dump file and stores it in the predefined directory. The default directory path is different for each platform:

  • Windows %localappdata%\JxBrowser\7.21.2\CrashReports
  • macOS $HOME/Library/Application Support/JxBrowser/7.21.2/CrashReports
  • Linux $HOME/.config/jxbrowser/7.21.2/crash-reports

To change the default directory use the jxbrowser.crash.dump.dir system property. For example:

System.setProperty("jxbrowser.crash.dump.dir", "/Users/Me/.jxbrowser/7.21.2/CrashReports");


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:


Using JxBrowser in Java 9+

There are cases when JxBrowser requires access to non-public APIs. In Java 9+ you must explicitly grant this access to JxBrowser. In this section, we list such cases.

Embedding into Swing in the HARDWARE_ACCELERATED mode

In the HARWARE_ACCELERATED rendering mode on Windows and Linux, the library uses the internal JDK API to correctly traverse the input focus between Java and Chromium windows.

Export the required package to the unnamed module if your application is non-modular:

--add-exports java.desktop/sun.awt=ALL-UNNAMED

Or export the required package to the JxBrowser modules if the application is modular:

--add-exports java.desktop/sun.awt=jxbrowser.swing

Embedding into JFXPanel

If you embed BrowserView into JavaFX which is inside of JFXPanel, the library will require access to JavaFX’s internal API to obtain the native handle of the application window.

Export the required packages to the unnamed module if your application is non-modular:

--add-opens javafx.swing/javafx.embed.swing=ALL-UNNAMED
--add-exports javafx.controls/com.sun.javafx.scene.control=ALL-UNNAMED

Or export the required packages to the JxBrowser modules if the application is modular:

--add-opens javafx.swing/javafx.embed.swing=jxbrowser
--add-exports javafx.controls/com.sun.javafx.scene.control=jxbrowser

Illegal Reflective Access

Running JxBrowser on Java 9 and higher might produce the following warning message in console:

WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by <CLASS> to field <FIELD>
WARNING: Please consider reporting this to the maintainers of <CLASS>
WARNING: Use --illegal-access=warn to enable warnings of further 
         illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

This warning can be observed only if you use Java 9 and higher. The matter is that support for modules introduced in Java 9 is not currently supported by JxBrowser, so there is such a warning for our reflection inside the library.

We recommend just disregarding this message. It does not influence any JxBrowser functionality. If you wish to hide it, you will need to configure Java to disable some output to console. The solution can be found in the corresponding StackOverflow discussion.

Cannot Sign In to Google Account

An attempt to sign in to Google Account leads to the following message:

Google Account Sign In Error

The reason of this issue is the following. When Remote Debugging Port is used, Chromium blocks any attempt to log in to its services (e.g. Gmail, YouTube).

To resolve this Chromium security restriction, you should not configure Engine with the remote debugging port.

Out of Memory In Docker

By default, Docker runs a container with a /dev/shm shared memory space 64MB. This is typically too small for Chromium and will cause Chromium to crash when rendering large pages.

Since version 7.10, JxBrowser uses /dev/shm to store the bitmaps when the off-screen rendering mode is used. It allocates additional ~10MB (1080p) or ~40MB (4k) for each web page to store its bitmap.

To solve this issue run the Docker container with the docker run --shm-size=1gb command to increase the size of /dev/shm.

Choose Password for New Keyring

The keyring represents the encryption storage backend to use. By default, Chromium chooses the best option available on your PC.

Choose password for new keyring

If you see this dialog when launching JxBrowser and you would like to skip it, then please specify the BASIC password store type using the following option during Engine instantiation:

Engine engine = Engine.newInstance(
Go Top