Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

Application doesn’t have access to a protocol

Jay splits Wayland protocols into unprivileged and privileged. By default, applications only have access to unprivileged protocols. If a program like a screen locker, status bar, clipboard manager, or screen-capture tool is not working, it likely needs access to one or more privileged protocols.

Common symptoms include:

  • swaylock does nothing or fails to lock the screen (needs session-lock).
  • waybar or i3bar shows no workspace information (needs foreign-toplevel-list).
  • wl-copy / cliphist cannot access the clipboard (needs data-control).
  • grim or slurp cannot capture the screen (needs screencopy).

Quick fix – grant all privileges:

The simplest approach is to launch the program with full access to all privileged protocols. In your config, set privileged = true in the exec action:

on-idle = {
    type = "exec",
    exec = {
        prog = "swaylock",
        privileged = true,
    },
}

Or from the command line:

~$ jay run-privileged waybar

Better fix – grant only the capabilities needed:

Use a client rule to grant specific capabilities:

[[clients]]
match.comm = "waybar"
capabilities = ["layer-shell", "foreign-toplevel-list"]

See Granting Privileges for the full list of capabilities and more advanced approaches using connection tags.

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.

Screen sharing doesn’t work

Screen sharing requires PipeWire and the Jay desktop portal.

1. Check that PipeWire is running:

~$ systemctl --user status pipewire

If it is not running, start it:

~$ systemctl --user start pipewire

2. Check that the portal files are installed:

Jay needs two files to be found by the XDG desktop portal framework:

  • A portal definition file (e.g. /usr/share/xdg-desktop-portal/portals/jay.portal).
  • A portal configuration file (e.g. /usr/share/xdg-desktop-portal/jay-portals.conf).

These files are included in the Jay repository under etc/. If you built Jay from source and did not install them, copy them manually:

~$ sudo cp etc/jay.portal /usr/share/xdg-desktop-portal/portals/
~$ sudo cp etc/jay-portals.conf /usr/share/xdg-desktop-portal/

3. Restart the portal:

~$ systemctl --user restart xdg-desktop-portal

See the Screen Sharing chapter for more details.

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.

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