Skip to content

Troubleshooting

Common error states and known gaps, organized by symptom.

"Hotkey doesn't fire"

macOS

  • Accessibility permission not granted. Open System Settings → Privacy & Security → Accessibility, find the running interpreter (or Cue.app for a built bundle), enable the toggle, and restart Cue. Without this, CGEventTap cannot observe global key events.
  • Cmd is held down. Cmd+Shift+Space is the privacy toggle; the suggestion hotkey is the bare Shift+Space.
  • Cue is currently in privacy pause. Hotkey is a no-op until pause clears. Check for the red-border overlay.

Windows

  • The hotkey registers without prompts. If it doesn't fire, check the tray for the Cue icon — the app may have failed to start. Look at cue.log in the data root for the underlying error.
  • No API key. First-launch prompts; if dismissed, set it via Preferences → General → Anthropic API key.
  • API call failed. Check cue.log for an Anthropic error (rate limit, auth, network). The popup waits for a streamed response; on error it closes silently.
  • Selected-text grab took too long. Cue waits up to ~250 ms for the clipboard after simulating Cmd+C / Ctrl+C. If your app is slow to respond, the popup proceeds without the selected text.

"Streaming recorder keeps dying"

The streaming recorder is a subprocess. If you see it restart in a loop in cue.log, look for the underlying signal:

  • SIGSEGV (rc=-11) — typically a dynamic library mismatch. On macOS, make sure GStreamer.framework is installed system-wide and that you're not running Cue from a shell where miniforge or conda is active (their dylibs override the framework's and can segfault PyGObject). See Dev environment for the supported install path.
  • SIGTRAP (rc=-5) — under hardened runtime on macOS, missing com.apple.security.cs.allow-jit entitlement. Frozen builds ship with this enabled; it's only an issue if you're hand- building without the entitlements file.
  • Clean exits looping — usually the rotator decided the chunk was done and started a fresh one. That's expected every ~30 seconds in normal operation.

"Privacy pause stuck on"

  • Persistent secure input. Some apps (notably some VPN clients, certain remote desktop sessions) can hold the system-wide secure-event-input latch open longer than expected. Quitting that app should release it; if not, log out and back in. macOS exposes the latch via IsSecureEventInputEnabled and Cue mirrors that state.
  • Blocked app rule still matches. Check the foreground app against your block list in Preferences → Privacy. Window-title regexes apply too — if the title contains "Login", "Password", etc., the rule may be firing unexpectedly.

"Cue blocks a system auth dialog"

If a Touch ID / password prompt feels unresponsive while Cue is running, it's a known interaction. Cue's streaming recorder registers a pynput keyboard tap; if the recorder is force-killed without quitting Cue itself (so the parent watchdog doesn't fire), the orphan tap can interfere with secure-input dialogs.

Mitigations:

  • The watchdog auto-reaps the recorder when the parent dies. Normal exit paths (menu Quit, system shutdown) are safe.
  • If you do see a stuck dialog, quit Cue from the menu bar. The dialog should respond again within a second.

"Digest never updates"

  • Streaming is off. Digests run on the streaming pipeline. Enable Streaming in Preferences → General.
  • Privacy pause has been on for the whole window. Each digest cycle filters paused intervals; if the entire 15-minute window was paused, the digest pipeline produces a tombstone row.
  • Local backend is selected, model not yet downloaded. Status banner under Preferences → General shows the download state.

Known gaps

Some scenarios are not currently covered:

  • macOS UAC-style elevation prompts run on the secure desktop. User-mode code can't enumerate that desktop, so the red-border overlay can't render there. Pause still fires when focus returns to the regular desktop.
  • Windows console password prompts inside cmd.exe with no separate dialog window: UIA can't see them. Use manual pause or open passwords in a tool that surfaces a real dialog.
  • Audio and clipboard are not captured at all. If a future feature ever adds them, the privacy-pause and PII-scrub layers must be re-audited for that path.

Where to look first

  • cue.log (rolling) — most application errors.
  • privacy.log — pause enter/exit history with reasons.
  • The data root — listed in Preferences → Data → "Open data folder".

If something looks like a bug, please open an issue with the relevant log excerpt (PII is scrubbed before being written to either log file).