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.

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

   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.

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.