Migration

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.

Startup Failure on 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.

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:

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.

If the actions above do 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

Windows

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 %localappdata%\JxBrowser directory.

To change the default directory please use the jxbrowser.crash.dmp.dir System Property. For example:

macOS

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 /Users/<username>/Library/Logs/DiagnosticReports/ directory.

You can also find the generated crash dump files in the Console application:

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 /etc/profile:

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 core.%e.%p.%t name.

Logging

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.

Levels

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:

-Djxbrowser.logging.level=ALL

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:

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:

-Djxbrowser.logging.file=jxbrowser.log

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.