Common Issues
The grab-bag of “why isn’t this working?” questions, with the answers.
The hotkey doesn’t summon the overlay
Most common cause: another app has registered the same combination first.
Xenocept logs a warning at startup if it can’t register the global hotkey. Check the logs (Xenocept main window → Settings → Diagnostics → View Log) for messages like:
WARN: failed to register global hotkey Ctrl+Backquote (already in use)
Pick a different binding in Hotkeys. The new value is applied immediately — no restart needed.
Other causes:
- On macOS, Screen Recording permission hasn’t been granted yet (see Platform Notes).
- On Linux/Wayland, the desktop portal denied the binding — try a less-common combination.
- The Xenocept process isn’t running. Check the tray.
The overlay appears but the screen behind it isn’t frozen
This usually means the capture pipeline failed but the overlay rendered anyway. Symptoms: the overlay shows a transparent or stale image, and you can see the live screen through it.
- On macOS: confirm Screen Recording permission is enabled and that you’ve restarted Xenocept since granting it.
- On Linux/Wayland: confirm the desktop portal selection chose “All screens” (not “None” or a single window) the first time you pressed the hotkey.
- On Linux/X11: rare; usually means another XShm consumer is holding the buffer. Try restarting Xenocept.
Annotations don’t show up
If you’re drawing and nothing appears:
- Confirm you’re inside an active comment region (click-drag to make one).
- Check the active tool’s color isn’t matching the background — pure white strokes on a white background are invisible.
- Look at the diagnostics panel for any frontend errors. A plugin error can in rare cases break the rendering pipeline.
Submit hangs or never completes
Submit fans out to every configured delivery target in parallel. The overall Submit operation waits for all targets to either succeed or exhaust retries.
If one target is misconfigured (a URL with no listener, an unreachable IPC socket), Submit will appear to hang while that target backs off. Eventually (around 30 seconds for HTTP) the target fails and Submit completes.
Workarounds:
- Disable the broken target in Delivery Targets and re-Submit.
- Reduce the retry count for known-flaky targets.
The snapshot is already safely stored locally by the time delivery starts. You can re-deliver later.
A previous session resumed when I didn’t want it to
Xenocept does not persist in-progress session state across app restarts — every fresh hotkey press resets the canvas. If you’re seeing stale state, possibilities are:
- The overlay window had been hidden but never relaunched between sessions; in-memory state survives an
Esc-hide. Press the hotkey to fully reset. - You opened a submitted session in edit mode (from the Sessions list). Submitting from edit mode creates a new session, leaving the original intact.
I can’t find my old snapshots
Snapshots are stored locally in the AeorDB-backed store. They appear in the main UI’s snapshot browser. If the browser is empty:
- Check that you’re running the same Xenocept install (same user, same OS). The store is per-user.
- Confirm the data directory hasn’t been wiped — see Storage Layout for the path.
- Look at the diagnostics panel for any errors loading the store. A corrupted store would surface here.
The app starts but the Tauri window doesn’t open
The Tauri window opens on first launch but is intentionally closeable without quitting the app. If the window doesn’t appear:
- Click the tray icon to reopen the main window.
- If the tray icon isn’t visible either, Xenocept may have failed to start. Run from a terminal (
./xenocept) and look at stdout/stderr for errors.
How do I uninstall?
There’s no separate uninstaller right now:
- Delete the Xenocept binary.
- (Optional) Delete the data directory — see Configuration Overview for paths. This removes your snapshot history and settings.
A package-manager-friendly distribution is planned.
Where do I report bugs?
See the project README in the xenocept-client repository for issue tracking and contact information.