Common Issues

Overlay does not appear

• Confirm you are on Wayland.
• Run wayscriber --active from a terminal to see errors.

Keybind does not toggle

• Make sure the daemon is running.
• Check your compositor shortcut settings.
• Verify the command is wayscriber --daemon-toggle.
• Make sure you only defined the toggle once.
• If the overlay appears and immediately disappears, look for duplicate shortcut entries or key-repeat bursts.
• If the shortcut environment cannot find wayscriber, use the absolute path from command -v wayscriber.

Tray icon is missing

• Some panels hide StatusNotifier icons.
• Run with --no-tray if you do not need the tray.
• If the tray icon is blank or the menu shows square placeholders (Noctalia/Quickshell), start the daemon with WAYSCRIBER_TRAY_FORCE_PIXMAP=1.

Capture shortcuts do nothing

• Ensure wl-clipboard, grim, and slurp are installed (see Installation → Build from source if you are not using packages).
• Check your config under [capture].
• On GNOME, portal capture may ask for permission and can be slower. If freeze does not start, check the desktop portal service.
• On newer Sway/wlroots stacks, update Wayscriber before debugging deeper; older builds could bind a screencopy path that did not provide the shared-memory frames Wayscriber needs.

Configurator does not launch

• Install wayscriber-configurator.
• Or set WAYSCRIBER_CONFIGURATOR to its path.