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.

Web UI shows only “Config Editor (Safe Mode)”

Your config.yml is valid YAML, but it has a setting Frigate rejects. Fregata doesn’t quit: Frigate starts in safe mode instead. The web UI shows a single page, Config Editor (Safe Mode), with the note “Frigate is in safe mode due to a config validation error.” No cameras run in safe mode, so nothing is detected or recorded until the config is fixed. Your auth:, proxy: and database: blocks are still read, so sign-in works as usual.

Every problem is listed in the Frigate log (tray menu, Settings → Open Frigate Logs) under a “Config Validation Errors” banner:

Line #  : 12
Key     : cameras -> driveway -> detect -> min_initialized
Value   : 1
Message : Input should be greater than or equal to 2

Key is the path to the setting Frigate rejected. Line # is a best-effort hint and can read Unknown. Fix the setting in the safe-mode editor and choose Save & Restart, or edit ~/Fregata/config/config.yml and click Restart Frigate. Frigate validates strictly, so a misspelled key is flagged too.

Frigate keeps restarting instead? Two cases skip safe mode:

• The file isn’t valid YAML (wrong indentation, a stray tab, an unclosed quote). Frigate can’t read the file at all, so it has nothing to fall back to. The log ends with a YAML parse error that names a line and column, and the tray shows Frigate exiting and retrying up to five times before it stops. Any editor with YAML support will point at the bad line.
• Safe mode can’t start either, for example because the auth: or database: block is itself invalid. The log ends with “Unable to start Frigate in safe mode.” and the tray behaves the same way.

Fix config.yml, then start Frigate again from the tray.

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 with the box below.

Settings UI

1. In the web UI, go to Settings → Global configuration → FFmpeg. To change one camera only, use Settings → Camera configuration → Streams (FFmpeg) and pick the camera.
2. For Input arguments (under Advanced Settings on the global page), choose Manual arguments and enter: -avoid_negative_ts make_zero -fflags +genpts+discardcorrupt -rtsp_transport tcp -timeout 5000000 -use_wallclock_as_timestamps 1
3. Click Save.

An input that sets its own Input arguments (under Camera inputs) ignores this setting; change that input’s arguments instead.

YAML

# For every camera whose inputs don't set their own input_args
ffmpeg:
  input_args: -avoid_negative_ts make_zero -fflags +genpts+discardcorrupt -rtsp_transport tcp -timeout 5000000 -use_wallclock_as_timestamps 1

# Or for one input of one camera
cameras:
  frontdoor:
    ffmpeg:
      inputs:
        - path: rtsp://user:[email protected]:554/stream
          input_args: -avoid_negative_ts make_zero -fflags +genpts+discardcorrupt -rtsp_transport tcp -timeout 5000000 -use_wallclock_as_timestamps 1
          roles: [detect, record]

TCP is already the default (preset-rtsp-generic), so this only matters if input_args was changed to something else, such as preset-rtsp-udp.

One camera restarts far more than the others, with “vt decoder cb: output image buffer is null”

vt decoder cb: output image buffer is null: -12909
hardware accelerator failed to decode picture
Decode error rate 1 exceeds maximum 0.666667
No frames received from <camera> in 20 seconds. Exiting ffmpeg...
Restarting ffmpeg...

Unlike a software decoder, which tends to skip a bad frame and carry on, VideoToolbox hard-aborts the whole picture when a stream is lossy or not fully H.264-compliant. ffmpeg then exits, the 20-second watchdog restarts it, and the cycle repeats — sometimes hundreds of times a day, drowning out every other camera’s log lines. This is a property of that camera’s stream, not your Mac: aging cameras, or an encoder struggling under bitrate/motion load (errors cluster in daytime/high-motion hours and go quiet overnight), are the usual cause. Pull a diagnostic bundle or grep the raw log — if this signature is heavily concentrated on one camera while the others are quiet, that camera’s stream is the problem, not your setup or network.

The fix is to force software decode for just that camera:

config.yml only. The Settings UI cannot write an empty hwaccel_args list.

cameras:
  frontdoor:
    ffmpeg:
      hwaccel_args: []

This drops the -hwaccel videotoolbox flag for that camera’s detect ffmpeg input, so decoding falls back to software — a decoder that degrades gracefully on bad frames instead of hard-aborting and restart-looping. It’s the same CPU trade covered in Performance → Software decode, just triggered by a malformed stream instead of an unsupported codec.

Detection

Detector inference time is 50+ ms

Detection has fallen back to CPU. See Performance — Detector fell off the ANE.

The detector runs on the GPU although Inference backend is Neural Engine

If building the Neural Engine model crashes the detector, Fregata moves that detector to the GPU (ML Program format) instead of restarting in a loop. macOS 27.2 beta 1 does this: Apple’s Core ML compiler crashes on the bundled model. frigate.log then shows a warning starting CoreML: the detector crashed (SIGSEGV), and every later start logs Running it on the GPU (ML Program format) instead.

The switch applies only to what crashed: that macOS build, that Mac, that ONNX Runtime version and that model file. Fregata tries the Neural Engine again by itself when any of them changes, for example after a macOS update. To try again now, quit Fregata, delete ~/Fregata/state/coreml_ane_guard.json, and open Fregata. If the crash is still there, it moves back to the GPU after one more restart.

Diagnostic bundles include that file (which crash, when, on which macOS build). Please send one if this happens to you.

“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. When that happens on the Neural Engine path, Fregata retries the model on the GPU for that start and logs Retrying on the GPU (ML Program format). 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.

Settings UI

1. In the web UI, go to Settings → Fregata (macOS) → Global configuration → Apple Silicon Detector.
2. Set Inference backend to Metal GPU.
3. Click Save, then Restart when the page asks.

YAML

detectors:
  coreml:
    type: coreml
    inference_backend: gpu

Detection got worse (missed small/distant objects) after raising a camera’s resolution

Frigate caches an expected crop size per zone of the frame, learned from that camera’s own detection history, and never wipes it — switching to a higher detect.width/detect.height leaves it mixed with entries still sized for the old, lower resolution, indefinitely. Clear it from Settings → Maintenance → Region grid in the web UI. See Detection tuning — Raised detect.width/detect.height? Reset the region grid for the full explanation.

Enrichment models

A search, face match, or plate read is unusually slow right after starting Fregata

Expected, not a bug. The first real semantic search, face-recognition match, or license-plate read in a fresh Frigate process pays a one-off cold-start cost — sometimes tens of times slower than normal — that clears after a call or two and doesn’t come back until the next restart. See AI Models for Frigate Enrichments → The first inference after each restart is slower too for why.

Face recognition never recognizes anyone after enabling it

Detection still works — boxes appear, face_rec_fps ticks along — but nothing is ever identified. POST /faces/recognize always returns {"success": false, "message": "No face was recognized."}, and POST /faces/reprocess returns {"success": false, "message": "Model is still training, please try again in a few moments."} and never moves past it, even though nothing is actually training. Registering faces still works.

This happens only the very first time you enable face recognition, and only if a face gets detected before the one-time model download (a small landmark-detection file) finishes. The recognizer never picks up the file once it lands, so it stays stuck for the rest of that run. Restart Fregata once — after enabling face recognition and letting the initial download finish — and it works normally on that next start, and every start after that. This is an upstream Frigate startup-ordering bug, not specific to Fregata; see AI Models for Frigate Enrichments → Face recognition needs one extra restart the first time for why.

“Face landmark model missing at … – face RECOGNITION is disabled”

Face landmark model missing at .../model_cache/facedet/landmarkdet.yaml -- face
RECOGNITION is disabled (detection is unaffected). Faces will be found but
never identified. Delete the facedet model directory to force a re-download.

If you see this right after enabling face recognition for the first time, it’s expected — the line logs before the model finishes downloading, not because it’s missing for good. Ignore the “delete the model directory” suggestion in that case; deleting it only restarts the same race on the next launch. Instead, wait for the download to finish and restart Fregata once (see above).

If you see this on a later restart, after face recognition has already worked normally, landmarkdet.yaml is genuinely missing or corrupt — deleting model_cache/facedet/ to force a clean re-download is the right fix in that case.

Apple Intelligence descriptions or chat do nothing

If you set provider: apple_intelligence under genai: and no descriptions or chat replies appear, the cause is almost always one of three things: the Mac is below macOS 27, Apple Intelligence is not turned on (or its model has not finished downloading), or the entry lists the embeddings role. Each one logs a specific warning. See Troubleshooting Apple Intelligence for the messages and fixes.

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.

Recordings play but the browser shows a black frame / “media failed to decode”

A browser-side codec problem, not a Fregata bug — confirm by opening the same clip in QuickTime or VLC, where it plays fine. Chromium reports PIPELINE_ERROR_DECODE; Safari reports “Media failed to decode.” Almost always the camera’s own stream is HEVC/H.265 (Fregata’s default record preset is H.264 and doesn’t transcode the record role — this is purely about what your camera sends), or the camera’s audio isn’t AAC. Since Safari is this product’s most-used browser, the one fix worth knowing by name is apple_compatibility — set ffmpeg.apple_compatibility: true on a camera whose HEVC stream you want to keep, which corrects the stream format some players (Safari included) are strict about. If you’d rather sidestep HEVC entirely, record that camera as H.264 instead. See Frigate’s common errors reference for the full codec-compatibility matrix, including the audio-codec and “smart codec” causes.

Settings UI

1. In the web UI, go to Settings → Camera configuration → Streams (FFmpeg) and pick the camera.
2. Turn on Apple compatibility.
3. Click Save.

To turn it on for every camera, use Settings → Global configuration → FFmpeg instead.

YAML

# For one camera
cameras:
  frontdoor:
    ffmpeg:
      apple_compatibility: true

# Or for every camera
ffmpeg:
  apple_compatibility: true

“Unable to keep up with recording segments” / “Too many unprocessed recording segments”

Your storage can’t absorb segments as fast as cameras produce them. Local SSDs essentially never hit this; it shows up almost exclusively when the media folder is on a network share (NAS over SMB or NFS) that’s stalling or too slow under sustained multi-camera write load — see Recordings & retention for Fregata’s own storage guidance, since this has a real history with certain NAS/SMB setups. First checks: confirm the share stays responsive under load (ls -la on it from Terminal shouldn’t visibly hang while cameras are recording), and try a local external drive for a day to isolate whether the network share is the bottleneck. If it’s local storage hitting this, the disk is likely too slow for your camera count/bitrate.

Recordings silently stop saving for one camera (video’s fine, audio track just never finalizes)

If that camera’s audio is pcm_alaw/pcm_mulaw (G.711 — common on budget IP cameras), it can’t be muxed into an MP4 container, and recording segments for that camera quietly never finalize even though live view and detection keep working. Fix: set ffmpeg.output_args.record: preset-record-generic-audio-aac for that camera to transcode its audio to AAC before muxing, or turn off audio recording for it.

Settings UI

1. In the web UI, go to Settings → Camera configuration → Streams (FFmpeg) and pick the camera.
2. Under Output arguments, find Record output arguments, choose Preset, and select Record (Generic + Audio to AAC) (preset-record-generic-audio-aac). To drop the audio instead, select Record (Generic, no audio).
3. Click Save.

That preset is Frigate’s default, so this fix applies to a camera whose record arguments were changed (for example to copy the audio unchanged).

YAML

cameras:
  frontdoor:
    ffmpeg:
      output_args:
        record: preset-record-generic-audio-aac

Recorded audio goes silent after about a day, and recordings run about 10 seconds late

This affects cameras that record audio. So far it has been seen on EZVIZ cameras connected directly to Fregata, not on cameras relayed through an NVR, and only where the camera’s recording input uses preset-rtsp-restream (an input that reads the camera through go2rtc). About 26 and a half hours after the camera’s recording process started (usually your last Fregata restart), all of these happen at once:

• The audio in that camera’s recordings goes silent. Video keeps recording normally.
• Recordings are labelled about 10 seconds later than the picture. Compare the camera’s burned-in clock with the time shown in the timeline. Clips cut by time start and end about 10 seconds early.
• Clips exported from that period have no usable audio, and their timing is off.
• If you inspect a recording segment with ffprobe, it holds one or two audio packets instead of the usual hundred or more.

Nothing is logged when it starts. It lasts until that camera’s recording process restarts, for example when you restart Fregata, and then comes back about 26 and a half hours later.

The cause: partway through a long recording, the audio timestamps that reach FFmpeg jump backwards. By default FFmpeg only discards a timestamp jump larger than 30 hours, so it accepts this one. The audio timeline stops advancing, and FFmpeg holds the video back while it waits for the audio to catch up, which is where the 10 second delay comes from.

The fix is to add -dts_error_threshold 60 to the camera’s FFmpeg global arguments. FFmpeg then discards any timestamp more than 60 seconds away from where it expects the next one, and times the audio from the samples it receives instead, so the audio stays continuous and in step with the picture. A healthy stream never gets near 60 seconds: with Fregata’s default input arguments, the recording process already exits when a camera sends nothing for 10 seconds.

Setting the global arguments replaces the defaults, so keep them and add the new one at the end. Apply it to each affected camera.

Settings UI

1. In the web UI, go to Settings → Camera configuration → Streams (FFmpeg) and pick the camera.
2. Expand Advanced Settings below the other fields.
3. In FFmpeg global arguments, enter -hide_banner -loglevel warning -threads 2 -dts_error_threshold 60.
4. Click Save.

YAML

cameras:
  frontdoor:
    ffmpeg:
      global_args: -hide_banner -loglevel warning -threads 2 -dts_error_threshold 60

To check it worked, look at a recording from more than 26 and a half hours after the change: it should still have sound, and the timeline should match the camera’s burned-in clock to within about a second.

Once the setting has acted, FFmpeg writes a warning for each audio packet it re-times, ending in invalid dropping. These stay out of the log unless that camera’s recording process later fails. Fregata then logs the last 100 lines it printed, which will be these warnings rather than the error that stopped it.

“database disk image is malformed” / frigate.db won’t open

SQLite’s own integrity check has failed, usually from an unclean shutdown or a disk issue while it was mid-write (the config folder has to be on a local disk — see Default paths — so a flaky network mount isn’t the cause here the way it can be upstream). Quit Fregata first, back up frigate.db, then see Frigate’s database-recovery steps — the same PRAGMA integrity_check / REINDEX / rebuild process applies verbatim, just pointed at ~/Fregata/config/frigate.db instead of Frigate’s Docker path.

Timeline previews or the live scrubber go black right after relaunching Fregata

Different from the scenarios above — the recordings themselves are fine, only the short-lived preview/thumbnail cache is empty. That cache lives in Fregata’s RAM-disk (see Performance — RAM-disk cache), which is deliberately torn down whenever Fregata fully quits — a Restart Frigate from the tray keeps the same RAM-disk mounted and doesn’t lose it. It rebuilds automatically as new segments are processed; there’s nothing to repair.

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.

Phone app can’t connect, or no alerts

If Fregata Mobile can’t reach your Mac, or its alerts don’t arrive, check the Mac side first:

1. The address uses port 8971, such as https://<mac-ip>:8971, not 5000. Live view works over 5000, but while sign-in is on (the default) Frigate files the app’s alert registration under an anonymous user that has no account, so it reports success and saves nothing. Change the address to 8971 and run the app’s alert setup again.
2. Sign-in off is fine on Fregata. With Enable authentication off (Settings → System → Authentication), Fregata files alerts under the admin account it creates at first launch. Only if sign-in has been off since the very first launch is there no account to file them under: turn it on, restart Fregata, and use the app on port 8971.
3. Away from home, the app has an Away address that works from outside, such as a Tailscale address. See Fregata Mobile: away from home.
4. The Mac is reachable at all. The firewall and sleep causes under Web UI unreachable from another device on the LAN apply to the app too.

Then follow the app’s own troubleshooting pages, which explain each message it shows: Can’t connect, Alerts don’t arrive, Certificate questions and Live video problems. Still stuck? Getting help shows how to send a diagnostics report from the app.

App / launcher

“Blocked by Local Network privacy”

macOS has not granted Fregata local-network permission. Fregata still starts and keeps recording — this is a warning, not a blocker.

It only appears when the permission actually affects your setup, and the menu names exactly which connections are blocked. macOS restricts the local link: devices on the same subnet as your Mac, plus multicast, broadcast, and .local (Bonjour) name resolution. Cameras on a different subnet — a separate camera VLAN, for instance — are reached through your router and are unaffected, so nothing is reported for them.

Two ways to resolve it:

• Grant the permission. Click the warning in the menu, or go to System Settings → Privacy & Security → Local Network and enable Fregata. The warning clears on its own within about 30 seconds; no restart needed.
• Use IP addresses instead of .local names. If the blocked entry is a .local hostname, replacing it with the device’s IP address avoids Bonjour entirely and often the faster fix.

If nothing appears in the menu, nothing you use is affected, even if System Settings shows Fregata as disabled.

Already enabled in System Settings, but still blocked?

This is a known macOS bug, not a Fregata bug: macOS occasionally keeps denying local-network access to an app even after you’ve switched its toggle on in System Settings → Privacy & Security → Local Network. The Settings UI and the permission macOS actually enforces have gotten out of sync, and there’s no in-app or Settings action that forces them back in sync. A reboot is the fix — every case we’ve seen resolved this way.

Frigate doesn’t start, and the menu says “Waiting for /Volumes/…”

Fregata won’t start Frigate until its config and media folders both exist and can be written to. If either is on an external drive or a network share that isn’t mounted, it waits, rechecks every couple of seconds, and starts Frigate by itself the moment the folder is available. After a minute of waiting, a window tells you which drive or folder it is waiting for.

This is also what a Restart from the web UI runs into if the drive dropped off while Frigate was running. Frigate’s log stops at that restart, because Frigate hasn’t started again.

• “The drive … isn’t connected”: macOS doesn’t have the drive mounted. Check that it appears in Finder or Disk Utility. If it doesn’t appear anywhere, check its cable and power (or, for a share, the server). Granting Full Disk Access doesn’t help here: there is nothing mounted to grant access to.
• “Fregata can’t use its … folder”: the drive is there, but the folder can’t be created or written. The usual causes are a read-only disk (macOS mounts NTFS disks read-only), folder permissions, or a network share that has stopped responding.

To stop waiting and use a different folder, choose Settings → Folders → Change Media Location… (or Change Config Location…) in the tray menu.

Before Frigate stops, its log usually shows the drive going away: Input/output error while writing a recording, then [Errno 13] Permission denied: '/Volumes/<drive name>' over and over. That second error is Frigate trying to recreate the missing drive’s folder under /Volumes, which only macOS can do. It means the drive is gone, not that Fregata lacks permission.

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.