- Spell Checker
This guide describes how to troubleshoot issues while working with the library.
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:
- Make sure that your environment meets the system requirements for Windows.
- 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.
Startup Failure on Linux
If JxBrowser fails to start in your Linux environment, please perform the following actions:
- Make sure that your environment meets the system requirements for Linux.
- 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.
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.
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
To change the default directory please use the
jxbrowser.crash.dmp.dir System Property. For example:
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
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/core.exe_name.pid.time 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
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
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
JxBrowser supports the following logging levels:
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
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:
You can also set the required logging level using JxBrowser Logging API:
import com.teamdev.jxbrowser.logging.Level; import com.teamdev.jxbrowser.logging.Logger; ... Logger.level(Level.ALL);
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:
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.
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:
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
IllegalAccessException with the following message is thrown:
class com.teamdev.jxbrowser.internal.util.ReflectionUtil cannot access class com.sun.javafx.stage.WindowHelper (in module javafx.graphics) because module javafx.graphics 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 javafx.graphics/com.sun.javafx.stage=ALL-UNNAMED --add-exports javafx.graphics/com.sun.javafx.scene=ALL-UNNAMED --add-exports javafx.graphics/com.sun.javafx.scene.traversal=ALL-UNNAMED --add-exports javafx.graphics/com.sun.javafx.tk=ALL-UNNAMED --add-exports javafx.graphics/com.sun.glass.ui=ALL-UNNAMED --add-exports java.desktop/sun.awt=ALL-UNNAMED