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:
- Enable logging.
- Reproduce the issue.
- Take a thread dump when the application is frozen.
- 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:
var 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.