Snag help › Snag for the desktop
Troubleshooting
Start with snag doctor
snag doctorIt prints one line per check, marked:
| Mark | Means |
|---|---|
ok | working |
-- | not working, and Snag still does its job without it |
!! | not working, and something wanted will not happen |
Groups, in order: session, idle detection, observation, tray, credential, storage, queue, network, and desktop config hints (Hyprland rules and binds found or missing).
It exits 0 when every line is ok and 1 otherwise.
snag doctor is read-only: it creates no config file or database and changes nothing, so it is safe to run first and to run repeatedly. It works with no display, no daemon, no keyring and no network.
snag doctor --json gives the same facts as JSON. Paste that, with snag --version, into a bug report. It never contains the token.
Common problems
| Symptom | Check |
|---|---|
start, stop or toggle says no daemon is running | start it: systemctl --user start snag, or snag run |
snag run exits with code 3 | a daemon is already running in this session |
| Windows open at half the screen on Hyprland | the window rules from contrib/hypr/ are missing; the rules must match on title as well as class |
| A window rule does nothing | Hyprland 0.53 and later use match:class <regex> (a space, not a colon); an old-style rule silently never matches |
| No tray icon | no tray host is running, or the bar keeps tray icons in a collapsed drawer; snag doctor reports the tray host. The timer window and keybinds work without it |
| No running time in the bar | add the custom/timer module from contrib/waybar/ (or contrib/quickshell/); the tray cannot draw text in Waybar |
| No idle prompts | the compositor lacks ext-idle-notify-v1, or idle is off (--no-idle) or advisory; see snag doctor |
| The timer runs but nothing reaches the server | snag whoami: the token may be missing, expired or in a locked keyring. snag doctor shows the queue depth and the network check |
snag login says there is no secret service | start one (for example gnome-keyring-daemon --components=secrets) or open the locked keyring |
| The service hangs at start | the keyring is locked and waiting for its password |
| The capture box says "cannot file" | the banner gives the reason: no token, a missing ability, or the server not answering. snag login with a new token fixes the first two |
| The capture box refuses with no project | default_project names a project that does not exist; fix the name in the config file |
| Notes are refused | the token lacks knowledge:write; create a new token with it |
| The service has no window or tray under systemd | the user manager lacks the session environment; see Installing |
| After a reboot the first sync fails | expected when the network comes up after Snag; it retries within 30 seconds |
Logs
journalctl --user -u snag -fA missing tray host, a locked keyring and an unreachable server are all logged, and none of them stop the app.
For more detail, run the daemon by hand with RUST_LOG=debug snag run.
Back to Snag help