wry/book/src/troubleshooting.md

Troubleshooting

Jay doesn't start / black screen

Jay requires at least one working renderer -- without one, no GPU can be initialized and nothing will be displayed. It supports Vulkan (via libvulkan plus a GPU-specific driver) and OpenGL (via libEGL and libGLESv2). These libraries are loaded at runtime, not linked at build time. Vulkan is the primary renderer and should be used whenever possible; the OpenGL renderer is maintained only for backwards compatibility.

Check that the required libraries are installed:

~$ ls /usr/lib/libEGL.so* /usr/lib/libGLESv2.so* /usr/lib/libvulkan.so* 2>/dev/null

Note

On some distributions (e.g. Fedora, Debian), 64-bit libraries live in /usr/lib64/ or /usr/lib/x86_64-linux-gnu/ instead.

If nothing is listed, install the appropriate packages. See the Installation chapter for package names by distribution.

Nvidia users:

• You need Linux 6.7 or later for explicit sync support, which is required for Nvidia GPUs.
• Make sure the Nvidia Vulkan ICD (Installable Client Driver) is installed. Jay's Vulkan renderer is the recommended option on Nvidia hardware.

No applications open

The built-in default configuration binds:

• Super_L (left Windows key) -- open Alacritty.
• alt-p -- open bemenu as an application launcher.

If neither application is installed, nothing will happen when you press these keys. Either install them or create a custom configuration with your preferred applications:

~$ jay config init

Then edit ~/.config/jay/config.toml to change the terminal and launcher bindings.

Important

If you created a config file manually (e.g. by touching an empty file), it will have no shortcuts at all. Jay replaces the entire built-in default when any config file exists. Always use jay config init to start with a working configuration.

Wrong keyboard layout

The default keyboard layout is US QWERTY. To change it:

Option 1 -- edit the config:

~$ jay config init

Then edit the keymap.rmlvo section in ~/.config/jay/config.toml:

[keymap.rmlvo]
layout = "de"

Option 2 -- change it at runtime:

~$ jay input seat default set-keymap-from-names -l de
~$ jay input seat default set-keymap-from-names -l us -v intl

This takes effect immediately but does not persist across restarts unless configured in the config file.

X11 applications don't work

Jay uses Xwayland to run X11 applications.

1. Install Xwayland:

• Arch Linux: sudo pacman -S xorg-xwayland
• Fedora: sudo dnf install xorg-x11-server-Xwayland
• Debian/Ubuntu: sudo apt install xwayland

2. Check your configuration:

If you have a config file, make sure Xwayland is not explicitly disabled:

[xwayland]
# Make sure this is not set to false:
# enabled = false

Xwayland is enabled by default. You can also check its status at runtime:

~$ jay xwayland status

Display manager doesn't show Jay

1. Check that the session file exists:

~$ ls /usr/share/wayland-sessions/jay.desktop

If it does not exist, create it:

~$ sudo tee /usr/share/wayland-sessions/jay.desktop > /dev/null << 'EOF'
[Desktop Entry]
Name=Jay
Comment=A Wayland Compositor
Exec=jay run
Type=Application
DesktopNames=jay
EOF

2. Check that jay is in the system PATH:

If you installed Jay via cargo install, the binary is at ~/.cargo/bin/jay. Display managers typically do not include ~/.cargo/bin in their PATH. Either:

• Add ~/.cargo/bin to the system PATH, or
• Create a symlink:

~$ sudo ln -s ~/.cargo/bin/jay /usr/local/bin/jay

How to check logs

Open the log file in a pager:

~$ jay log

Follow the log in real time (like tail -f):

~$ jay log -f

Print just the log file path:

~$ jay log --path

Increase log verbosity at runtime:

~$ jay set-log-level debug

To set the log level at startup, add it to your config:

log-level = "debug"

Note

The log-level config setting is read at startup and cannot be changed by reloading the configuration. Use jay set-log-level for runtime changes.

To automatically clean up old log files, see Log File Cleanup.

Performance issues

If you experience dropped frames, stuttering, or high latency, try the following:

1. Use the Vulkan renderer:

The Vulkan renderer is generally faster and supports more features (e.g. HDR, direct scanout). Check your current API and switch if needed:

~$ jay randr show
~$ jay randr card card0 api vulkan

2. Set CAP_SYS_NICE:

Granting CAP_SYS_NICE allows Jay to use real-time scheduling and high-priority Vulkan queues, which improves responsiveness under load:

~$ sudo setcap cap_sys_nice=p $(which jay)

You need to re-run this command each time you update the Jay binary.

3. Adjust the flip margin:

The flip margin controls the time between initiating a page flip and the display's vblank. A smaller margin reduces input latency but risks missed frames. The default is 1.5 ms:

~$ jay randr card card0 timing set-flip-margin 1.5

If you see missed frames, try increasing it. If you want lower latency, try decreasing it -- Jay will dynamically increase it if the margin is too small.

4. Enable direct scanout:

Direct scanout allows fullscreen applications to bypass the compositor's rendering pipeline entirely, reducing both latency and GPU usage:

~$ jay randr card card0 direct-scanout enable