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

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.