Frequently encountered issues

This guide describes how to troubleshoot frequently encountered issues.

Startup failure on Windows

If JxBrowser does not start on Windows make sure the environment meets system requirements and no antivirus software interferes with it.

JxBrowser runs Chromium in a separate native process. Sometimes an antivirus software or a local security policy doesn’t allow the native process to start. Even though JxBrowser executable files are signed with a valid and trusted signature, 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 does not start on Linux make sure the environment meets system requirements and has necessary system libraries.

In some Linux distributions, the Chromium process can’t start because of missing system. When this happens, the library writes details in the logs.

Enable logging and check if the log messages contain errors like this:

java.lang.UnsatisfiedLinkError: /tmp/JxBrowser/VERSION/libbrowsercore_toolkit.so:
    libgobject-2.0.so.0: cannot open shared object file: No such file or directory

To resolve this issue, install the missing libraries.

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

Slow startup

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

The JxBrowser startup process consists of several steps. First, it extracts the Chromium binaries stored in JAR files. Then it launches the main Chromium process and sets up the connection between Java and the Chromium processes.

Normally, the extraction of the Chromium binaries occurs only once in the environment. This step may noticeably slow down the startup. For example, it takes additional ~3 seconds on the i7/16GB RAM/512GB SSD machine. Learn how to skip this step here.

Antivirus software may check library binaries before allowing JxBrowser to launch them. This negatively affects the startup time. Please try disabling the 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.

Chromium process crash

JxBrowser runs Chromium in a separate native process. An error in this process may lead to unexpected process termination. When this happens, the library generates one or multiple crash dump files. These files are essential for understanding the cause of the crash.

If Chromium process is unexpectedly terminated and you received the EngineCrashed event, then please report the issue and attach the generated crash dump file/files.

Freeze in Java application

If your Java application hangs and you believe it happens because of JxBrowser, follow these steps:

1. Enable logging.
2. Reproduce the issue.
3. Take a thread dump when the application is frozen.
4. Report the issue and attach the collected thread dump and the log messages.

Video does not play

The 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.

Overlapping JMenu

In the Hardware Accelerated rendering mode, BrowserView will overlay the menu bar:

The reason of this issue is in mixing the lightweight pop-up menu and the heavyweight BrowserView. To fix this it, disable the lightweight mode of the Swing pop-ups:

JPopupMenu.setDefaultLightWeightPopupEnabled(false);

JPopupMenu.setDefaultLightWeightPopupEnabled(false)

This code forces all Swing pop-up menus to become heavyweight.

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 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 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-opens javafx.graphics/com.sun.javafx.stage=ALL-UNNAMED
--add-exports javafx.graphics/com.sun.javafx.stage=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-opens javafx.graphics/com.sun.javafx.stage=jxbrowser
--add-exports javafx.graphics/com.sun.javafx.stage=jxbrowser
--add-exports javafx.controls/com.sun.javafx.scene.control=jxbrowser

Cannot sign in to Google account

An attempt to sign in to Google Account may lead to the following message:

The reason of this issue may be the remote debugging port. When the port is configured, Chromium blocks any attempt to log in to its services (e.g. Gmail, YouTube).

Out of memory in Docker

By default, Docker runs a container with a /dev/shm shared memory space of 64MB. This is too little for Chromium and will cause crashes when during rendering the pages.

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

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

On Linux, Chromium may create a new keyring and the operating system will show this dialog:

To prevent this from happening, configure Chromium to use the BASIC password store instead of the system password store:

Engine engine = Engine.newInstance(
        EngineOptions.newBuilder(renderingMode)
                     .passwordStore(PasswordStore.BASIC)
                     .build());

val engine = Engine.newInstance(
        EngineOptions.newBuilder(renderingMode)
                     .passwordStore(PasswordStore.BASIC)
                     .build())

ObjectClosedException

Service objects in the library API may be closed. An attempt to call a closed object leads to an ObjectClosedException exception.

In this guide, we explain common scenarios when a service object can be closed and what you can do about it.

Closed Engine

The topmost object in JxBrowser is Engine. There are two situations when it can be closed:

• The Engine::close() method is called;
• An error occurs in the Main Chromium process.

If you close an engine, all objects associated with it such as profiles, browsers, frames, etc. will be closed automatically. So, after the engine is closed, regardless of the reason, make sure not to use any of the objects associated with the closed engine.

If an error occurs in the Main Chromium process, the process will be terminated and the engine is closed. When it happens the library generates crash dump files and stores them in a specific directory. Use the EngineCrashed event to be notified when it happens.

In this case, please report the issue and attach the crash dump files.

Deleted Profile

Profiles can be deleted by calling the Profiles::delete() method.

If you delete a profile, all objects associated with it such as cookie store, browsers, frames, DOM/JS objects, etc. are closed automatically. So, after you delete a profile, make sure not to use any of the objects associated with the deleted profile.

Closed Browser

There are two situations when Browser can be closed:

• The Browser::close() method is called;
• JavaScript closes the window.

If you close a browser, all objects associated with it such as navigation, text finder, frames, DOM/JS, etc. will be closed automatically. So, after the browser is closed, make sure not to use any of the objects associated with the closed browser.

The window.close() method in JavaScript can only close a browser that was opened by another script. If you expect this to happen, consider checking the browser status before using it.

Please note that when JavaScript closes the browser Java discovers it with a slight delay. If the browser is already closed but Java is not yet notified, the attempt to use the closed browser will lead to ObjectClosedException.

Unloaded web page

Each loaded web page has a main frame and child frames. When navigating to a web page, the browser unloads the previously loaded page and deletes all the frames and DOM/JS objects in it.

Make sure to not use DOM and JavaScript objects after the web page gets unloaded. Use the navigation events to get notified.

Please note that Java receives navigation events with a slight delay. If the page is already unloaded, but Java is not yet notified, the attempt to use deleted/closed objects will lead to ObjectClosedException.

Terminated render process

In Chromium, frames reside in render processes. When the render process is terminated, the frame is deleted. When the frame is deleted the web page, its DOM and JavaScript objects are deleted and closed too.

Use the RenderProcessTerminated event to get notified when the process is terminated. If the process is terminated unexpectedly, please report the issue and attach the generated crash dump files.

If it is terminated normally, no action is required.