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/current (a symlink to the active rotation). Open from the tray with Open Crash Log when Fregata is in an error state.
• Older logs — ~/Fregata/logs/ retains a few rotations.
• 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 licence

”Couldn’t reach the licensing service”

The activation HTTP call to the Cloudflare Worker failed. Most common causes:

1. No network. Verify with any other browser request.
2. DNS / captive portal. Hotel and conference Wi-Fi sometimes intercepts the request. Try a tethered phone or a different network.
3. Corporate firewall blocking *.workers.dev (older licensing server) or licensing.fregata.app (current). Add an allow.
4. 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”.

”Licence key not recognised”

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 licence 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-licence page first”. Do that, then retry.

”License expired” or “Token failed verification”

If you’ve been offline for more than 7 days, the cold-start grace window has elapsed and the cached token has expired. Reconnect to the network and click Activate in the tray menu — the existing key in the Keychain is still good, the request just needs to succeed.

If you’re online and the token is still rejected, the licensing server’s signing key may have rotated. The fix in that case is to update Fregata to a current build; expired keys are detected client-side, key-rotation issues require new code.

Frigate / Python core

”Frigate exited unexpectedly — restarting in Ns (N/5)”

Tray status. The 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 Open Crash Log 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 (detectors.coreml.model_path removed) 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: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 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 lower 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

The app crashed and the supervisor exhausted its 5 restart attempts. Check Console.app → Crash Reports → User → Fregata for the underlying crash. Re-launch the app 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.

Reaching us

If none of the above fits:

• GitHub Discussions — github.com/3rdBitLabs/Fregata/discussions. Slow but public; great for permanent archive of the answer.
• Email — reply to your licence email, or support@fregata.3rdbitlabs.com. Faster, private. Paid customers get priority.

When reporting an issue, attach (or paste a relevant chunk of) ~/Fregata/logs/current and the output of About Fregata… → Copy Diagnostic Info. That’s enough to reproduce most problems on our side.