- User Data Profiles
- Credit Cards
- Spell Checker
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.
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.
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:
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
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:
Or export the required package to the JxBrowser modules if the application is modular:
If you embed
BrowserView into JavaFX which is inside
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
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
Engine engine = Engine.newInstance( EngineOptions.newBuilder(renderingMode) .passwordStore(PasswordStore.BASIC) .build());
val engine = Engine.newInstance( EngineOptions.newBuilder(renderingMode) .passwordStore(PasswordStore.BASIC) .build())
Service objects in the library API may be closed.
An attempt to call a closed object leads to an
In this guide, we explain common scenarios when a service object can be closed and what you can do about it.
The topmost object in JxBrowser is Engine. There are two situations when it can be closed:
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.
EngineCrashed event to be notified when it happens.
In this case, please report the issue and attach the crash dump files.
Profiles can be deleted by calling the
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.
There are two situations when
Browser can be closed:
Browser::close()method is called;
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.
a browser that was opened by another script. If you expect this to happen, consider
checking the browser status before using it.
closed but Java is not yet notified, the attempt to use the closed browser will lead to
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.
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
Terminated Render Process
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.