# 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:
```shell
~$ 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](installation.md) 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](https://alacritty.org/).
- `alt-p` -- open [bemenu](https://github.com/Cloudef/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:
```shell
~$ 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:
```toml
on-idle = {
type = "exec",
exec = {
prog = "swaylock",
privileged = true,
},
}
```
Or from the command line:
```shell
~$ jay run-privileged waybar
```
**Better fix -- grant only the capabilities needed:**
Use a client rule to grant specific capabilities:
```toml
[[clients]]
match.comm = "waybar"
capabilities = ["layer-shell", "foreign-toplevel-list"]
```
See [Granting Privileges](window-rules.md#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:**
```shell
~$ jay config init
```
Then edit the `keymap.rmlvo` section in `~/.config/jay/config.toml`:
```toml
[keymap.rmlvo]
layout = "de"
```
**Option 2 -- change it at runtime:**
```shell
~$ 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:**
```shell
~$ systemctl --user status pipewire
```
If it is not running, start it:
```shell
~$ 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:
```shell
~$ 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:**
```shell
~$ systemctl --user restart xdg-desktop-portal
```
See the [Screen Sharing](screen-sharing.md) 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:
```toml
[xwayland]
# Make sure this is not set to false:
# enabled = false
```
Xwayland is enabled by default. You can also check its status at runtime:
```shell
~$ jay xwayland status
```
## Display manager doesn't show Jay
**1. Check that the session file exists:**
```shell
~$ ls /usr/share/wayland-sessions/jay.desktop
```
If it does not exist, create it:
```shell
~$ 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:
```shell
~$ sudo ln -s ~/.cargo/bin/jay /usr/local/bin/jay
```
## How to check logs
Open the log file in a pager:
```shell
~$ jay log
```
Follow the log in real time (like `tail -f`):
```shell
~$ jay log -f
```
Print just the log file path:
```shell
~$ jay log --path
```
Increase log verbosity at runtime:
```shell
~$ jay set-log-level debug
```
To set the log level at startup, add it to your config:
```toml
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](configuration/misc.md#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:
```shell
~$ 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:
```shell
~$ 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:
```shell
~$ 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:
```shell
~$ jay randr card card0 direct-scanout enable
```