Skip to main content

Troubleshooting

Common Desktop Agent problems and how to fix them.

Agent says no active window backend​

Log / error:

active window: no active window backend available for this desktop session

Meaning: none of the OS backends returned a focused window.

Checklist:

  1. Confirm your DE is supported — see Supported platforms.
    XFCE and similar DEs are not supported.
  2. On GNOME Wayland: ensure the Shell extension is enabled (Linux desktops).
  3. On KDE Wayland: ensure the KWin script is enabled, then focus any window once.
  4. On Hyprland / Sway: confirm hyprctl / swaymsg work in the same session.
  5. On X11: install xprop and/or xdotool.
  6. Restart: ./Analog-WakaTime-Agent stop && ./Analog-WakaTime-Agent start

status shows GNOME / KDE helper not active​

Follow the manual steps in Linux desktops.

Quick recovery:

./Analog-WakaTime-Agent stop
./Analog-WakaTime-Agent start
./Analog-WakaTime-Agent status

On KDE, switch windows once after start so the script emits the first focus event.

Agent running but queue only grows​

Symptom: Offline sync queue keeps increasing; dashboard stays empty.

Checks:

  1. status → Account must be authenticated (run login if not)
  2. Network / VPN / firewall to the gateway
  3. logs/agent.log for sync postponed
  4. Clock skew on the machine (expired tokens)

Data is not lost while queued locally.

failed to enable agent: remove data/agent.disabled: ...​

On some platforms, removing a missing disable file used to surface as an error. Current builds treat “file already absent” as success. Update the binary if you still see this on first start.

Worker dies immediately after start​

./Analog-WakaTime-Agent status
tail -n 100 logs/agent.log

Look for DB open errors, permission errors on data/ / logs/, or repeated tracker crashes. Ensure the working directory is writable.

Windows build errors (Setsid, syscall.Kill, GetWindowText)​

You are on an outdated tree. Current agent sources split Unix/Windows daemon code and call GetWindowTextW via user32. Rebuild from the fixed branch.

macOS returns empty / permission errors​

Grant Automation access for the terminal (or the agent binary) to control System Events under Privacy & Security, then rerun.

Duplicate agents / stale PID​

If a crash left a stale data/agent.pid:

./Analog-WakaTime-Agent stop
# if needed, remove data/agent.pid manually after confirming no process holds it
./Analog-WakaTime-Agent start

Still stuck?​

Collect:

  • OS + desktop (echo $XDG_CURRENT_DESKTOP $XDG_SESSION_TYPE)
  • ./Analog-WakaTime-Agent status output
  • last lines of logs/agent.log
  • whether you use Wayland or X11

That is usually enough to tell whether you hit an unsupported DE (for example XFCE) or a helper install issue on GNOME/KDE.