Troubleshooting

Troubleshooting

Every entry below is a symptom, the checks to run, and the fix. If your problem is not here, ask in Discussions or open an issue.

---

Tracking shows "unknown"

Nothing is being recorded, or every session is filed under unknown.

Check 1 — is the daemon running?

systemctl --user status screenguard

If it is not active, see The daemon is not running below.

Check 2 — GNOME Wayland: is the shell extension enabled?

gnome-extensions list --enabled | grep screenguard
gnome-extensions info screenguard@screenguard.app | grep -i state

The state must be ACTIVE. If it is not:

gnome-extensions enable screenguard@screenguard.app

Check 3 — is accessibility (AT-SPI) enabled?

ScreenGuard identifies applications through AT-SPI on GNOME.

gsettings get org.gnome.desktop.interface toolkit-accessibility   # expect true

On Debian, Ubuntu and Fedora the package post-install script enables this and copies the extension for you. If you installed by a route that skips post-install (Arch, or a manual tarball), run it once:

sudo /usr/share/screenguard/enable_fedora_a11y.sh

Check 4 — Flatpak apps

Sandboxed applications need permission to expose themselves over AT-SPI. Grant it in Settings → Privacy → Screen for the Flatpak apps you want tracked, or use the flatpak override:

flatpak override --user --talk-name=org.a11y.atspi.EventSocket your.app.id

Check 5 — X11

On X11 nothing extra is needed, but xprop must exist:

which xprop xdotool

---

Nothing is tracked on KDE Plasma Wayland, Sway or Hyprland

This is expected. Native Wayland tracking is implemented for GNOME only. On other compositors, log into an X11 session — ScreenGuard tracks fully there via EWMH.

Native support for KDE Plasma and Hyprland/Sway (through wlr-foreign-toplevel-management) is on the Roadmap.

---

The daemon is not running

systemctl --user status screenguard

It says inactive. The daemon needs an active graphical session (graphical-session.target), so it only starts once you are logged in.

systemctl --user enable --now screenguard

It says failed. Read the log:

journalctl --user -u screenguard -n 50 --no-pager

It exits immediately at every start. Another daemon already holds the lock file. That is normal when the old process is still shutting down; if it persists:

systemctl --user stop screenguard
rm -f ~/.local/share/screenguard/daemon.lock
systemctl --user start screenguard

The GUI offers to set it up every time. That prompt appears until you pick an option. It is recorded in the daemon_initial_choice setting.

---

The GUI says the daemon is not running

The GUI reads a heartbeat file that the daemon rewrites every five minutes. If the GUI cannot find a fresh heartbeat, it shows a banner.

ls -l ~/.local/share/screenguard/daemon_heartbeat
systemctl --user status screenguard

A stale heartbeat with a running daemon means the daemon is wedged. Restart it from Settings → Diagnostics, or:

systemctl --user restart screenguard

---

A limit does not trigger

1. Check that the limit is enabled for that application.
2. Check that the application is actually being tracked under the expected name — the dashboard's per-day breakdown shows the exact name used for the limit.
3. On X11, minimising a window needs xdotool:

which xdotool
sudo apt install xdotool

4. Enforcement only fires while the daemon runs. A GUI-only session tracks nothing.

---

The focus session does not block an app

• The application must be ticked in the distraction list on the Focus Mode tab.
• Only applications that appear in the list of installed apps can be ticked — search for it, or check the dashboard for the exact tracked name.
• The blocker needs the daemon running.

---

Updates are not being offered

Beta releases are hidden by default, and this surprises people:

• Settings → Updates → Include Beta Versions must be enabled to see pre-release versions.
• The check runs once a day by default. Use Check now to force it.
• If the update check is disabled, the app will never look.

---

I want to reset everything

systemctl --user stop screenguard
rm -f ~/.local/share/screenguard/usage.db*
systemctl --user start screenguard

This removes all usage history. Limits and other settings live in the same database, so they are reset as well. To keep your limits but drop the history, use Settings → Data → Clear all usage history in the GUI.

---

Something crashed

Local crash logs are kept in:

~/.local/share/screenguard/crashes/

Settings → Diagnostics lists them, lets you read the stack trace and open a pre-filled GitHub issue with your environment attached. The tab carries a badge with the number of stored crash logs.

Anonymous diagnostics are opt-out — Settings → Diagnostics has a Send Anonymous Diagnostics switch (crash reports and the daily active-install ping), plus a Send test ping button to check connectivity. Turning it off keeps crash logs on your machine but sends nothing.

---

Reporting a bug well

The single most useful thing you can attach is proof:

• a screenshot or a short screen recording of the problem,
• your desktop environment and version (for example KDE Plasma 6.1, GNOME 46),
• your session type (Wayland or X11),
• the ScreenGuard version (Settings → Updates shows it).

X11 bugs are especially hard to reproduce without proof, so please include the video.

---

Related: Getting Started · Architecture · Feedback