Skip to content

Common Issues

ScreenStop icon not appearing in menu bar / system tray

macOS:

  1. Check if the process is running: 
    pgrep -l ScreenStopMenu
  2. If not running, launch manually: 
    open /Applications/ScreenStop/ScreenStopMenu.app
  3. If it launches but disappears, check the log: 
    cat ~/Library/Application\ Support/ScreenStop/screenstop.log | tail -50

Windows:

  1. Check Task Manager for ScreenStopTray.exe
  2. Launch manually from C:\Program Files\ScreenStop\ScreenStopTray\ScreenStopTray.exe

Camera permission denied (macOS)

ScreenStop requires camera access to function.

  1. Go to System Settings > Privacy & Security > Camera
  2. Enable access for ScreenStopMain
  3. Restart ScreenStop from the menu bar icon

Station not appearing in dashboard

  1. Confirm the machine has network access to the dashboard URL
  2. Check the log for connection errors
  3. Verify SCREENSTOP_DASHBOARD_URL is set to the correct address

Screen locking too aggressively / false positives

Adjust detection thresholds in the Dashboard:

  • Increase phone_confidence to reduce false phone detections
  • Increase face_confidence to reduce false unauthorized person detections
  • Disable specific detection modes that are causing issues

Camera not found / black frames

  1. Confirm the webcam is physically connected
  2. On macOS, check for zombie processes holding the camera: 
    sudo lsof | grep -i "VDC\|camera\|avconference"
  3. Release the camera: 
    sudo killall VDCAssistant 2>/dev/null
  4. Restart ScreenStop

Dashboard timestamps showing wrong time

If events appear with incorrect timestamps (e.g., 2 hours behind), this is a timezone mismatch issue fixed in v1.0.3.

Upgrade to the latest version to resolve this.

Icons showing default app icon after build (macOS)

This is a macOS icon cache issue. It resolves on its own after a system restart, or you can clear the cache manually:

sudo find /private/var/folders -name "com.apple.dock.iconcache" -exec rm -f {} \; 2>/dev/null
sudo killall Dock

Fixed automatically at build time as of v1.0.3.

ScreenStop icon appears in the Dock (macOS)

ScreenStop is a background daemon and should not appear in the Dock. If you see its icon there, it is cosmetic only — the app cannot be quit from the Dock (only "Open" is shown). The daemon continues running normally.

This resolves automatically after reinstalling with v2.0.0 or later.

USB drive not being ejected (USB Protection enabled)

  1. Confirm USB_PROTECTION is enabled for the station's department in the Dashboard
  2. Confirm the station has no authorized person present — USB eject only fires when detection determines the workstation is unattended or accessed by an unauthorized person
  3. Check the log for USB_PROTECTION_ACTIVE entries to confirm the feature is running: 
    grep "USB_PROTECTION" ~/Library/Application\ Support/ScreenStop/screenstop.log
  4. On macOS, confirm the USB drive is a storage device — ScreenStop does not eject keyboards, mice, or audio devices
  1. Confirm PRINT_PROTECTION is enabled for the station's department in the Dashboard
  2. Check the log for PRINT_PROTECTION_ACTIVE entries
  3. On macOS, confirm CUPS is running: 
    lpstat -r
  4. Note: Print Protection cancels jobs that are pending or held. Jobs that have already reached the printer cannot be recalled.

Audit Mode not suppressing locks

If locks are still firing when AUDIT_MODE = true:

  1. Confirm the department policy was saved and the station has checked in (allow up to 10 seconds)
  2. Check the log for AUDIT_MODE: lock suppressed — if absent, the config has not propagated yet
  3. Verify AUDIT_MODE in the station's effective config: 
    grep "AUDIT_MODE" ~/Library/Application\ Support/ScreenStop/screenstop.log | tail -5

Docker — Dashboard container fails to start

Check the container logs: 

docker compose logs screenstop

Common causes:

Error Fix
DASHBOARD_SECRET_KEY is required Add DASHBOARD_SECRET_KEY=<secret> to your .env file
Address already in use Port 443 or 80 is already bound — stop the conflicting service
cert.pem not found Ensure CERTS_DIR points to a directory containing cert.pem and key.pem

Docker — Agents cannot connect to dashboard (TLS error)

If agents are reporting connection errors after switching to HTTPS:

  1. Confirm the agent's dashboard_url is set to https:// (not http://)
  2. If using a self-signed certificate, agents will reject it by default. Either:
  3. Use a certificate signed by your internal CA and deploy the CA cert to workstations
  4. Set DASHBOARD_VERIFY_SSL=false in the agent's AppData config (testing only — not recommended for production)
  5. Check the agent log for the exact error:

=== "macOS" 

grep -i "ssl\|certificate\|connect" ~/Library/Application\ Support/ScreenStop/screenstop.log | tail -20

=== "Windows" 

findstr /i "ssl certificate connect" "%LOCALAPPDATA%\ScreenStop\screenstop.log"

Docker — Cannot log in after fresh deployment

On a fresh deployment with no users in the database, you must bootstrap using dev mode:

  1. Add SCREENSTOP_DEV_MODE=true to .env
  2. Restart: docker compose down && docker compose up -d
  3. Log in with admin / admin
  4. Go to Admin → Users and create your real admin account
  5. Remove SCREENSTOP_DEV_MODE=true from .env and restart again

See Docker Deployment — Bootstrap Admin Account.

Log level not changing from dashboard

Changing LOG_LEVEL in the dashboard applies on the next detection cycle without a daemon restart. This was a bug fixed in v1.0.3 — upgrade if you're on an earlier version.