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.

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.

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.

“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:

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.

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:

   ffprobe -rtsp_transport tcp 'rtsp://user:[email protected]: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 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:

   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.

“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.
• “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. (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. <mac-name>.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.

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 or Bartender. Full walkthrough: 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 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):

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 for how to post a public question on GitHub Discussions or contact the team directly by email. When you do, attach a diagnostic bundle (Settings → Troubleshooting → Create Diagnostic Bundle…) — it gives the team your logs, config, and system state from one shareable ID.