# Troubleshooting This page is indexed by **what you see** — pick the error message or the symptom that matches and skip to that section. If the exact string isn't here, search GitHub Discussions; we add new entries as they come up. ## Where the logs live - **Live log** — `~/Fregata/logs/frigate/current`, on the SSD. Open it from the tray with **Settings → Open Frigate Logs** (launches Console.app following the live log), or **Reveal Logs in Finder**. It persists across restarts and crashes, so it's there when you need to see why something failed. - **Other services** — `~/Fregata/logs/go2rtc/current` and `~/Fregata/logs/nginx/current`. Each file is capped at ~5 MiB; once a file crosses that, the oldest ~2 MiB are chopped and ~3 MiB of tail is kept. - **Early-startup stderr** — captured in memory by the Swift launcher (first 16 KB before the file redirect kicks in). The launcher uses this to detect `FATAL:` lines and surface a user-readable error instead of a silent crash. ## Activation and license ### "Couldn't reach the licensing service" The activation HTTP call to the licensing server failed. Most common causes: 1. **No network.** Verify with any other browser request. 2. **Corporate firewall** blocking `licensing.fregata.app`. Add an allow. 3. **System clock skew.** The activation token's signature validates against the current time. If your Mac's clock is more than ~5 minutes off, requests are rejected. Check **System Settings → General → Date & Time** is set to "Set automatically". ### "License key not recognized" The key didn't match anything on the server. Three possibilities: 1. **Typo / whitespace.** The key has the form `frgt_XXXX-XXXX-XXXX-XXXX`; trailing whitespace from a copy-paste is the most common version. 2. **Wrong email.** The activation server checks the license key *and* the email together. They must match what was on the purchase / trial-request. 3. **Already bound elsewhere.** If the key is already activated on another Mac, the response says "already bound, release from the manage-license page first". Do that, then retry. ### "License expired" or "Token failed verification" If more than 7 days have passed since your last successful license validation (typically because the Mac was offline at the most recent restart), the cached license key will be rejected at startup. Reconnect to the network and click **Activate** in the tray menu — the existing key is still good, the request just needs to succeed. ## Frigate / Python core ### "Frigate exited unexpectedly — restarting in Ns (N/5)" Tray status. The Frigate Python core died and the supervisor is backing off before the next attempt (1 s, 2 s, 4 s, 8 s, 16 s, max 30 s, up to 5 attempts). Use **Settings → Open Frigate Logs** to see why. The most common causes: - A camera URL is unreachable. ffmpeg can't open the input, Frigate's startup health check fails, the process exits. Solution: fix or remove the offending camera in `config.yml`. - Bad model file. A swapped ONNX is corrupt or has unexpected ops. Solution: revert to the bundled model (remove your `model.path` from `config.yml`) and try again. - Disk full. Recordings can't be written. Solution: free space or prune older recordings — see [Recordings & retention](/guides/recordings-and-retention/). ### "FATAL: config validation failed" Your `config.yml` has a syntax or schema error. The error message includes the YAML path of the offending key, e.g.: ``` FATAL: cameras.driveway.detect.fps: input should be greater than 0 ``` Open `~/Fregata/config/config.yml`, fix, and click **Restart Frigate**. Frigate validates strictly — typos in keys are usually flagged, but if you've used the wrong indentation, the message can be cryptic. A YAML linter (any editor with YAML support) will catch the indentation case. ### Web UI loads but cameras say "Stream not available" Almost always an upstream RTSP issue, not a Fregata one. 1. Test the URL with `ffprobe`: ```bash ffprobe -rtsp_transport tcp 'rtsp://user:pass@10.0.1.20:554/h264Preview_01_main' ``` 2. If `ffprobe` can't open it either, the URL is wrong, the credentials are wrong, or the camera is down. The [Cameras](/reference/cameras/) page has URL shapes for common brands. 3. If `ffprobe` works but Fregata doesn't, the most common cause is `udp` vs `tcp` transport. Force TCP in the camera config: ```yaml ffmpeg: input_args: -avoid_negative_ts make_zero -fflags +genpts+discardcorrupt -rtsp_transport tcp -timeout 5000000 -use_wallclock_as_timestamps 1 ``` ## Detection ### Detector inference time is 50+ ms Detection has fallen back to CPU. See [Performance — Detector fell off the ANE](/guides/performance/#detector-fell-off-the-ane). ### "Failed to compile model with CoreML" You swapped to a custom ONNX model and the CoreML compiler can't compile it. The compiler logs the unsupported op. Two fixes: 1. **Re-export with op set ≤ 17.** Most modern object-detector exports default to a newer op set; CoreML's compiler lags by a few months. Pass `--opset 17` (or 16) to your export script. 2. **Set `inference_backend: gpu`.** The Metal GPU path runs a broader op set than the ANE path. Latency jumps from ~2 ms to ~5–10 ms but the model works. ## Networking ### Web UI unreachable from another device on the LAN Three common causes: 1. **macOS firewall** blocking inbound. **System Settings → Network → Firewall → Options** — make sure Fregata.app is set to "Allow incoming connections". 2. **mDNS isn't reaching across subnets.** `.local` only resolves on the same broadcast domain. Use the IP directly or set up DNS. 3. **Port not listening.** `lsof -nP -iTCP:8971 -sTCP:LISTEN` should show `nginx`. If it doesn't, Frigate isn't fully started — check **Fregata Status** in the tray. ### HA can see the cameras list but not the streams The HA integration has reached `8971/api/config` but the live MSE / WebRTC streams are coming from a different port and HA's browser can't reach them. The fix is a reverse proxy that exposes the full host (including websocket upgrade) on a single hostname / port — see [Network & remote access](/guides/network-and-remote-access/). ## App / launcher ### "Could not access the local network" macOS revoked or never granted Fregata's local-network permission. The tray menu surfaces a banner. Go to **System Settings → Privacy & Security → Local Network** and ensure Fregata is enabled. The supervisor retries silently every few seconds; once permission is granted, the next attempt will succeed. ### Menu bar icon is gone Most of the time the icon is **hidden, not gone** — Fregata is still running. macOS hides menu-bar icons when the bar is full (especially on MacBooks, where the notch eats the middle), and no app can claim a fixed or "priority" slot. Hold **⌘** and drag icons to rearrange them, pull Fregata's 🐦 out from behind the notch, or use a menu-bar manager like [Ice](https://github.com/jordanbaird/Ice) or Bartender. Full walkthrough: [Finding the menu-bar icon](/guides/settings/#finding-the-menu-bar-icon). To stop this from happening again, turn on **Settings → Show Dock Icon** — a Dock icon is always visible regardless of how full the menu bar gets. To check whether Fregata is actually running, open [https://localhost:8971](https://localhost:8971) or look for the `Fregata` process in Activity Monitor. **If it really has quit:** the supervisor may have exhausted its 5 restart attempts after repeated crashes. Check **Console.app → Crash Reports → User → Fregata** for the underlying crash, then re-launch from /Applications — the supervisor counter resets on every launch. ### App won't open after macOS upgrade A macOS upgrade can invalidate the cached Gatekeeper assessment. Right-click Fregata.app → **Open** → confirm the dialog. After one manual open, the standard launch path works again. ### Reset Fregata settings If Fregata is stuck with wrong folder paths, won't show the welcome wizard after a reinstall, or you want to start completely fresh, you can wipe all Fregata app settings in one step. **From the menu (easiest):** 1. Click the Fregata menu-bar icon 2. Go to **Settings → Troubleshooting → Reset Fregata Settings…** 3. Read the confirmation and click **Reset and Restart** Fregata will clear all app settings and relaunch automatically. Your Frigate configuration (cameras, recording rules, `config.yml`) inside the config folder is untouched — only Fregata's own preferences (folder paths, environment variables, launch-at-login, etc.) are reset. **From the Terminal (if the menu is inaccessible):** ```sh defaults delete com.3rdbitlabs.fregata ``` Then relaunch Fregata from `/Applications`. This is exactly what the menu item does under the hood. :::note Deleting `~/Library/Preferences/com.3rdbitlabs.fregata.plist` directly does **not** reliably clear the settings — macOS caches preferences in memory and the old values can persist until a reboot. Always use `defaults delete` or the menu item above. ::: ## Reaching us If none of the above fits, see [Getting help](/guides/support/) for how to post a public question on GitHub Discussions or contact the team directly by email.