JCEF: the missing libs problem on Linux

Problem

JCEF, the browser component behind the Markdown preview, the embedded browser, and other web views, does not start on Linux. The symptom depends on the IDE version.

On 2026.x, the preview or browser panel stays empty and idea.log records:

SEVERE - #c.i.u.j.StartupTest - Startup JCEF test is failed (because CefApp wasn't initialized). JCEF will be restarted with verbose logging.
SEVERE - #c.i.u.j.StartupTest - Plugin to blame: Web Browser (JCEF) version: <build>-linux-x86_64

No library name appears in idea.log in this case. See Cause below.

On earlier versions, idea.log names the missing library directly:

java.lang.UnsatisfiedLinkError: /home/user/clion-2020.2/jbr/lib/libjcef.so: libXss.so.1: cannot open shared object file: No such file or directory

Cause

libcef.so and the cef_server executable have many shared-library dependencies. An incomplete Linux setup can miss some of them, and JCEF then fails to start. Distributions that install no X11 client libraries reach this state. NixOS on a Wayland-only desktop is one example. The desktop session needs nothing from X11, so the dependency is easy to miss.

Where the failure surfaces depends on how JCEF runs.

Out-of-process is the current default on Linux. The renderer runs in a separate cef_server executable under plugins/jcef-plugin/jcef/. The dynamic linker stops that process before it starts. No Java exception is raised, and nothing names the missing library in idea.log.

In-process applies to older versions. jbr/lib/libjcef.so is loaded from Java through System.loadLibrary, and jbr/lib/libcef.so is loaded dynamically from libjcef.so. A missing dependency raises UnsatisfiedLinkError, which is logged with the library name.

Resolution

1. List the unresolved dependencies, using the path that matches the IDE version:

# 2026.x, out-of-process
ldd /path/to/ide/plugins/jcef-plugin/jcef/cef_server | grep "not found"

# older versions, in-process
ldd /path/to/ide/jbr/lib/libcef.so | grep "not found"

Example output:

libXss.so.1 => not found

2. Check whether a given library is available to the dynamic linker:

ldconfig -p | grep libXss

3. Find the package that provides the missing library. pkgs.org maps library names to package names across distributions. On Debian and Ubuntu, apt-file search and aptitude search do the same locally:

sudo apt-get install libxss1

4. Repeat step 1 after each install. The dynamic linker reports one missing library at a time, so several rounds may be needed.

Restart the IDE after installing the libraries.