# 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. :::tip[Sharing logs with the team?] Instead of hunting down individual files, use **Settings → Troubleshooting → Create Diagnostic Bundle…** — it packages these logs together with your config, live stats, and system state into a single ID you can paste into a Discussion or email. See [Getting help → Create a diagnostic bundle](/guides/support/#create-a-diagnostic-bundle). ::: ## 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. **Did you just downgrade to an older version?** Then this is expected, and your config isn't broken — it's simply newer than the version now reading it. A major update rewrites `config.yml` into a newer shape (masks are the usual trigger), and that only runs forwards. Restore the backup Fregata made before it migrated: ```sh cp ~/Fregata/config/backup_config_0.17-0.yaml ~/Fregata/config/config.yml ``` The version in that filename is the one you upgraded *from*, so pick the one matching the version you're going back to — `ls ~/Fregata/config` shows what's there. See [Before you install a major update](/guides/updates-and-renewals/#before-you-install-a-major-update). ### 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. ## Recordings and playback ### Recordings, clips and exports show as grey (gray) boxes The tiles are there in the web UI, the scrubber is populated, but nothing plays — every video is an empty grey box. Cameras, detection and live view are all fine. This is what a migrated database looks like. Frigate **never scans the disk for media**. Every media route is driven by rows in `frigate.db`, and each row stores the *absolute path* of the file. If you brought a config folder over from another Frigate install — Frigate in Docker, or Frigate on another machine — those rows still hold the old install's paths (`/media/frigate/recordings/…` for a Docker install), and your media folder on this Mac is somewhere else. The rows render; the file fetch behind each tile 404s. The video files themselves are fine and open normally in Finder. The fix is to repoint the rows: 1. Click the Fregata menu-bar icon 2. **Settings → Troubleshooting → Repair Media Paths…** 3. Read what it found and click **Repair Now** Fregata backs up `frigate.db` next to itself first, then rewrites the stored path prefixes for recordings, preview clips, review thumbnails, exports and export thumbnails. **No video file is moved, copied, or deleted** — only the paths in the database change. If Frigate is running it is stopped for the rewrite and started again, so live view and recording pause for a few seconds. Reload the web interface afterwards. Fregata also runs this check itself on every launch, before Frigate starts, and offers the repair in a dialog. If you clicked **Don't Ask Again**, the menu item above still works — running it clears the suppression. Three variations: - **"Your recordings don't appear to be in your media folder"** — Fregata looked for the files at the new location and found none of them. You brought the database but not the video. Copy the `recordings`, `clips` and `exports` folders from the old install into your media folder first, then repair. - **"Nothing here that Fregata can repair"** — the offending entries don't match any layout Frigate writes, so Fregata can't work out where they should point. Nothing is changed. Open a thread in [GitHub Discussions](https://github.com/3rdBitLabs/Fregata/discussions). - **"Media path repair cannot continue"** — the database lists media under more than eight different previous locations, and Fregata won't guess which files belong where. Nothing is changed. Open a thread in [GitHub Discussions](https://github.com/3rdBitLabs/Fregata/discussions). (This message is also what you get if Fregata simply couldn't read the database.) Those last two only appear when you run **Repair Media Paths…** from the menu. Neither has a repair to offer, so on launch Fregata says nothing and just starts Frigate. ### No recordings appear at all after copying data across No tiles, no scrubber entries, nothing — as opposed to grey boxes. That's the *other* half of the same mistake: you copied the media folder but not `frigate.db`. The recordings, clips and exports are indexed nowhere, so there is nothing for the web UI to draw, and **Repair Media Paths…** can't help — it repairs entries, and there are no entries. Go back to the old install, copy `frigate.db` (plus `frigate.db-wal` and `frigate.db-shm` if they exist) into your config folder alongside `config.yml`, then run **Settings → Troubleshooting → Repair Media Paths…** so the paths in it match this Mac. If the old database is gone for good, so is the index: the video files stay on disk but Frigate will never show them, and only new recordings will appear. ## 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. When you do, attach a [diagnostic bundle](/guides/support/#create-a-diagnostic-bundle) (**Settings → Troubleshooting → Create Diagnostic Bundle…**) — it gives the team your logs, config, and system state from one shareable ID.