Miscellaneous fixes (#23648)

* sort preview cameras in history by ui order * sort cameras by UI order in various components for consistent display * add no recordings faq * fix link * recording cache faq * add link * improve anchor naming in object detector docs rather than #configuration-1, #configuration-2, etc * use yaml instead of json for object detector docs * fix anchor
2026-07-28 14:49:01 +03:00 · 2026-07-07 10:56:43 -06:00
parent 4ee12e6237
commit c99d6b0dcf
23 changed files with 1689 additions and 518 deletions
@@ -11,7 +11,7 @@ Frigate ships with a set of FFmpeg presets to keep your configuration short and

 In the config file you reference a preset by its name (for example, `preset-vaapi`). In the UI, the same preset is shown with a friendly label (for example, **VAAPI (Intel/AMD GPU)**). Both refer to the same thing — the tables below list the config name alongside the label you'll see in the UI.

-### Hwaccel (Hardware Acceleration) Presets
+### Hwaccel (Hardware Acceleration) Presets {#hwaccel-presets}

 Hardware acceleration arguments tell FFmpeg to decode your camera's video stream on a GPU or integrated graphics chip instead of the CPU, which dramatically lowers CPU usage. Using a preset is highly recommended. Beyond replacing a long list of arguments, each preset also tells Frigate what hardware is available so it can offload additional work to the GPU — for example, encoding the Birdseye restream or scaling a stream whose resolution differs from the camera's native size.

@@ -8,7 +8,7 @@ import ConfigTabs from '@site/src/components/ConfigTabs';
 import TabItem from '@theme/TabItem';
 import NavPath from '@site/src/components/NavPath';
 import ModelConfigDropdown from '@site/src/components/ModelConfigDropdown';
-import objectDetectorsModels from '@site/data/object_detectors_models.json';
+import objectDetectorsModels from '@site/data/object_detectors_models.yaml';

 ### Supported hardware

@@ -238,7 +238,7 @@ detectors:
 </TabItem>
 </ConfigTabs>

-### Configuration
+### Configuration {#configuration-edgetpu}

 <ModelConfigDropdown detectorTitle="EdgeTPU" models={objectDetectorsModels.edgeTPU.models} />

@@ -256,7 +256,7 @@ If no custom model is provided, the Hailo detector downloads a default model fro

 :::

-### Configuration
+### Configuration {#configuration-hailo}

 When configuring the Hailo detector, you have two options to specify the model: a local **path** or a **URL**.
 If both are provided, the detector will first check for the model at the given local path. If the file is not found, it will download the model from the specified URL. The model file is cached under `/config/model_cache/hailo`.
@@ -298,7 +298,7 @@ detectors:

 :::

-### Configuration
+### Configuration {#configuration-openvino}

 <ModelConfigDropdown detectorTitle="OpenVINO" models={objectDetectorsModels.openvino.models} />

@@ -308,12 +308,12 @@ detectors:

 The NPU in Apple Silicon can't be accessed from within a container, so the [Apple Silicon detector client](https://github.com/frigate-nvr/apple-silicon-detector) must first be setup. It is recommended to use the Frigate docker image with `-standard-arm64` suffix, for example `ghcr.io/blakeblackshear/frigate:stable-standard-arm64`.

-### Setup
+### Setup {#setup-apple-silicon}

 1. Setup the [Apple Silicon detector client](https://github.com/frigate-nvr/apple-silicon-detector) and run the client
 2. Configure the detector in Frigate and startup Frigate

-### Configuration
+### Configuration {#configuration-apple-silicon}

 Using the detector config below will connect to the client:

@@ -323,7 +323,7 @@ Note that the labelmap uses a subset of the complete COCO label set that has onl

 ## AMD/ROCm GPU detector

-### Setup
+### Setup {#setup-rocm}

 Support for AMD GPUs is provided using the [ONNX detector](#onnx). In order to utilize the AMD GPU for object detection use a frigate docker image with `-rocm` suffix, for example `ghcr.io/blakeblackshear/frigate:stable-rocm`.

@@ -401,7 +401,7 @@ We unset the `HSA_OVERRIDE_GFX_VERSION` to prevent an existing override from mes
 $ docker exec -it frigate /bin/bash -c '(unset HSA_OVERRIDE_GFX_VERSION && /opt/rocm/bin/rocminfo |grep gfx)'
 ```

-### Configuration
+### Configuration {#configuration-rocm}

 :::tip

@@ -455,7 +455,7 @@ detectors:

 :::

-### Configuration
+### Configuration {#configuration-onnx}

 <ModelConfigDropdown detectorTitle="ONNX" models={objectDetectorsModels.onnx.models} />

@@ -475,7 +475,7 @@ The number of threads used by the interpreter can be specified using the `"num_t

 A TensorFlow Lite model is provided in the container at `/cpu_model.tflite` and is used by this detector type by default. To provide your own model, bind mount the file into the container and provide the path with `model.path`.

-### Configuration
+### Configuration {#configuration-cpu}

 <ModelConfigDropdown detectorTitle="CPU" models={objectDetectorsModels.cpu.models} />

@@ -485,13 +485,13 @@ When using CPU detectors, you can add one CPU detector per camera. Adding more d

 The Deepstack / CodeProject.AI Server detector for Frigate allows you to integrate Deepstack and CodeProject.AI object detection capabilities into Frigate. CodeProject.AI and DeepStack are open-source AI platforms that can be run on various devices such as the Raspberry Pi, Nvidia Jetson, and other compatible hardware. It is important to note that the integration is performed over the network, so the inference times may not be as fast as native Frigate detectors, but it still provides an efficient and reliable solution for object detection and tracking.

-### Setup
+### Setup {#setup-deepstack}

 To get started with CodeProject.AI, visit their [official website](https://www.codeproject.com/Articles/5322557/CodeProject-AI-Server-AI-the-easy-way) to follow the instructions to download and install the AI server on your preferred device. Detailed setup instructions for CodeProject.AI are outside the scope of the Frigate documentation.

 To integrate CodeProject.AI into Frigate, configure the detector as follows:

-### Configuration
+### Configuration {#configuration-deepstack}

 <ModelConfigDropdown detectorTitle="DeepStack" models={objectDetectorsModels.deepstack.models} />

@@ -509,7 +509,7 @@ See the [installation docs](../frigate/installation.md#memryx-mx3) for informati

 To configure a MemryX detector, simply set the `type` attribute to `memryx` and follow the configuration guide below.

-### Configuration
+### Configuration {#configuration-memryx}

 <ModelConfigDropdown detectorTitle="MemryX" models={objectDetectorsModels.memryx.models} />

@@ -646,7 +646,7 @@ This implementation is based on sdk `v1.5.0`.

 See the [installation docs](../frigate/installation.md#synaptics) for information on configuring the SL-series NPU hardware.

-### Configuration
+### Configuration {#configuration-synaptics}

 When configuring the Synap detector, you have to specify the model: a local **path**.

@@ -759,7 +759,7 @@ Explanation of the paramters:

 DeGirum is a detector that can use any type of hardware listed on [their website](https://hub.degirum.com). DeGirum can be used with local hardware through a DeGirum AI Server, or through the use of `@local`. You can also connect directly to DeGirum's AI Hub to run inferences. **Please Note:** This detector _cannot_ be used for commercial purposes.

-### Configuration
+### Configuration {#configuration-degirum}

 #### AI Server Inference

@@ -853,7 +853,7 @@ The AXEngine detector downloads its default model from HuggingFace on first star

 :::

-### Configuration
+### Configuration {#configuration-axengine}

 When configuring the AXEngine detector, you have to specify the model name.

@@ -55,7 +55,7 @@ Frigate supports multiple different detectors that work on different types of ha
 **Most Hardware**

 - [Hailo](#hailo-8): The Hailo8 and Hailo8L AI Acceleration module is available in m.2 format with a HAT for RPi devices offering a wide range of compatibility with devices.
-  - [Supports many model architectures](../../configuration/object_detectors#configuration)
+  - [Supports many model architectures](../../configuration/object_detectors#configuration-hailo)
  - Runs best with tiny or small size models

 - [Google Coral EdgeTPU](#google-coral-tpu): The Google Coral EdgeTPU is available in USB and m.2 format allowing for a wide range of compatibility with devices.
@@ -3,6 +3,105 @@ id: recordings
 title: Recordings Errors
 ---

+## Why are my recordings not working? (empty Recordings, "No recordings found for this time")
+
+If Frigate shows live video but the History view is empty, or you see "No recordings found for this time", the cause is almost always in one of the three categories below. Segments are first written to the RAM cache and are only moved to disk if they match a retention policy _and_ the camera's `record` stream is producing valid, storable video. Work through the categories in order — retention configuration is by far the most common cause.
+
+Before diving in, enable debug logging for the recording maintainer so you can see whether segments are being written to disk at all:
+
+```yaml
+logger:
+  logs:
+    frigate.record.maintainer: debug
+```
+
+A healthy camera logs lines like `Copied /media/frigate/recordings/{segment_path} in 0.2 seconds`. If you never see these, no segments are reaching disk, which points at the camera/stream or storage sections below.
+
+### Retention configuration issues
+
+#### Recording is enabled, but nothing is saved
+
+This is the single most common cause. Setting `record.enabled: True` on its own does **not** keep any footage — **continuous recording is disabled by default**, and segments in the cache are only moved to disk if they match a configured retention policy. You must configure at least one of `continuous`, `motion`, `alerts`, or `detections` retention.
+
+To store all video (the most conservative option), configure continuous retention:
+
+```yaml
+record:
+  enabled: True
+  continuous:
+    days: 3 # keep all footage for 3 days
+```
+
+See [Recording](/configuration/record) for the full set of common configurations, including reduced-storage and alerts-only setups.
+
+#### Motion or event-only recording keeps less than you expect
+
+If you only configured `motion`, `alerts`, or `detections` retention (with no `continuous`), Frigate keeps footage selectively based on the retention `mode`:
+
+- **`mode: motion`** (the default) only retains segments that contain motion. If your [motion masks](/configuration/motion_detection) cover the areas where activity happens, or your motion sensitivity is too low, nothing will be retained even though recording is "on".
+- **`mode: active_objects`** only retains segments where a tracked object was actively moving.
+- **`mode: all`** retains every segment in the window.
+
+If you expected continuous footage but only configured motion/event retention, add a `continuous` retention period as shown above. To verify motion is actually being detected, watch the motion boxes in the debug view or the Motion Tuner in the UI.
+
+#### Alert and detection recordings require working object detection
+
+`alerts` and `detections` retention only keep footage that overlaps a tracked object, so they depend on object detection running:
+
+- **Detection must be enabled.** If `detect: enabled: False`, no alerts or detections are ever created, so alert/detection retention keeps nothing. (Continuous and motion retention still work with detection disabled.)
+- **The object must be supported by your model.** If you track an object your model doesn't support (for example `deer` or `license_plate` on the default model), Frigate never detects it and never records for it. Check your logs for warnings such as `... is configured to track ['deer'] objects, which are not supported by the current model` and remove unsupported objects or switch to a model (e.g. [Frigate+](/plus/)) that includes them.
+
+#### You're following an outdated guide
+
+Configuration keys change between major versions. The old `clips` config, for example, has not existed for a long time. If you copied a config from an old blog post or video, verify every key against the current [reference config](/configuration/advanced/reference).
+
+### Camera and stream issues
+
+#### Incompatible audio codec (recordings silently fail to save)
+
+Frigate stores recordings in an MP4 container, and some camera audio codecs — most commonly `pcm_alaw`, `pcm_mulaw`, or other G.711 variants — **cannot be placed in an MP4 container**. When this happens, ffmpeg fails to write the segment and no recording is saved, even though the live view works fine. This is a frequent cause on Tapo, TP-Link VIGI, and some Reolink cameras.
+
+Transcode the audio to AAC (or drop it entirely) using the appropriate [ffmpeg preset](/configuration/ffmpeg_presets):
+
+```yaml
+cameras:
+  your_camera:
+    ffmpeg:
+      output_args:
+        record: preset-record-generic-audio-aac # transcode audio to AAC
+        # or preset-record-generic to record with no audio
+```
+
+#### The record stream isn't connecting
+
+A message like `No new recording segments were created for <camera> in the last 120s` means ffmpeg cannot read the `record` stream. To diagnose:
+
+- Confirm a stream is actually assigned the `record` role in your camera's `ffmpeg.inputs`.
+- Open the go2rtc web interface on port `1984` and click each stream to confirm it plays. go2rtc errors such as `wrong response on DESCRIBE` or `start from CONN state` indicate the camera connection is failing.
+- Test the exact RTSP URL (with the correct path, port, and credentials) in VLC or `ffplay`.
+- If you restream through go2rtc, make sure the `record` input path points at the correct go2rtc stream name — copying a config between cameras without updating the stream name is a common mistake.
+
+#### Recordings play back with no video (or won't play at all)
+
+Frigate copies the `record` stream directly without re-encoding, so playback depends on your browser supporting the camera's codec. H265/HEVC recordings may not be playable in some browsers. If recordings appear as audio-only or a black screen, your camera is likely sending a codec your browser can't decode — configure the camera to output **H264** for maximum compatibility.
+
+#### Segments are only ~1 second long
+
+If the record stream uses a "Smart Codec"/H.264+ mode or changes encoding parameters mid-stream, corrupt timestamps cause segments to be split far too frequently and fill the cache. This produces the "Too many unprocessed recording segments" warning — see [that section below](#i-see-the-message-warning--too-many-unprocessed-recording-segments-in-cache-for-camera-this-likely-indicates-an-issue-with-the-detect-stream) for the full diagnosis.
+
+### Storage and mounting issues
+
+#### The storage volume isn't mounted correctly
+
+If the recordings volume (`/media/frigate`) points at the wrong location, isn't writable, or a network/encrypted mount failed to mount at boot, Frigate cannot save recordings — or it silently writes to the boot drive and then purges aggressively because the drive appears far smaller than expected.
+
+- Compare the host's real capacity (`df -h`) against what the **Storage** page in the Frigate UI reports. A mismatch (for example Frigate reporting ~220 GB when your storage drive is 4 TB) means the bind mount is resolving to the wrong filesystem.
+- Verify the host path in your Docker `volumes` mapping (`- /your/storage:/media/frigate`) exists and is writable by the container.
+- For a mount that may fail intermittently, protecting the mount point with `chattr +i` on an empty directory forces Frigate to error out (rather than silently writing to the boot drive) when the mount is missing.
+- Check `dmesg` and system logs for filesystem or I/O errors around the time recordings disappeared.
+
+If recordings _are_ being written but the copy is too slow to keep up, see the ["Unable to keep up with recording segments"](#i-see-the-message-warning--unable-to-keep-up-with-recording-segments-in-cache-for-camera-keeping-the-5-most-recent-segments-out-of-6-and-discarding-the-rest) section below.
+
 ## I have Frigate configured for motion recording only, but it still seems to be recording even with no motion. Why?

 You'll want to:
@@ -13,7 +112,11 @@ You'll want to:

 ## I see the message: WARNING : Unable to keep up with recording segments in cache for camera. Keeping the 5 most recent segments out of 6 and discarding the rest...

-This error can be caused by a number of different issues. The first step in troubleshooting is to enable debug logging for recording. This will enable logging showing how long it takes for recordings to be moved from RAM cache to the disk.
+This warning means the recording maintainer cannot move recording segments from the RAM cache to disk fast enough. When the cache fills up, Frigate discards the oldest segments to avoid running out of memory and crashing — so you lose recorded footage. This is almost always a storage throughput or system resource problem. Work through the steps below to identify which.
+
+### Step 1: Enable recording debug logging
+
+The first step is to measure how long each segment takes to move from the RAM cache to disk. Enable debug logging for the recording maintainer:

 ```yaml
 logger:
@@ -21,31 +124,34 @@ logger:
    frigate.record.maintainer: debug
 ```

-This will include logs like:
+This adds log lines showing the copy duration for each segment:

 ```
 DEBUG   : Copied /media/frigate/recordings/{segment_path} in 0.2 seconds.
 ```

-It is important to let this run until the errors begin to happen, to confirm that there is not a slow down in the disk at the time of the error.
+Let this run until the warnings begin to appear, so you can confirm whether the disk is actually slowing down at the moment the error occurs.

-#### Copy Times > 1 second
+### Step 2: Interpret the copy times

-If the storage is too slow to keep up with the recordings then the maintainer will fall behind and purge the oldest recordings to ensure the cache does not fill up causing a crash. In this case it is important to diagnose why the copy times are slow.
+The copy duration tells you which direction to investigate:

-##### Check RAM, swap, cache utilization, and disk utilization
+- **Consistently longer than ~1 second** — your storage cannot keep up with the incoming recordings. Continue with Steps 3–5 to diagnose the slow storage.
+- **Consistently well under 1 second** — storage is fast enough, and the problem is more likely CPU or resource contention. Skip to Step 6.

-If CPU, RAM, disk throughput, or bus I/O is insufficient, nothing inside frigate will help. It is important to review each aspect of available system resources.
+### Step 3: Check RAM, swap, cache, and disk utilization

-On linux, some helpful tools/commands in diagnosing would be:
+If CPU, RAM, disk throughput, or bus I/O is insufficient, nothing inside Frigate will help. Review each aspect of available system resources while the warnings are occurring.

- docker stats
- htop
- iotop -o
- iostat -sxy --human 1 1
- vmstat 1
+On Linux, some helpful tools/commands for diagnosing this are:

-On modern linux kernels, the system will utilize some swap if enabled. Setting vm.swappiness=1 no longer means that the kernel will only swap in order to avoid OOM. To prevent any swapping inside a container, set allocations memory and memory+swap to be the same and disable swapping by setting the following docker/podman run parameters:
+- `docker stats`
+- `htop`
+- `iotop -o`
+- `iostat -sxy --human 1 1`
+- `vmstat 1`
+
+On modern Linux kernels, the system will use some swap if it is enabled. Setting `vm.swappiness=1` no longer means the kernel will only swap in order to avoid OOM. To prevent any swapping inside the container, set the memory and memory+swap allocations to the same value and disable swapping by setting the following docker/podman run parameters:

 **Docker Compose example**

@@ -67,19 +173,19 @@ services:
 --memory=<MAXRAM> --memory-swap=<MAXSWAP> --memory-swappiness=0
 ```

-NOTE: These are hard-limits for the container, be sure there is enough headroom above what is shown by `docker stats` for your container. It will immediately halt if it hits `<MAXRAM>`. In general, running all cache and tmp filespace in RAM is preferable to disk I/O where possible.
+NOTE: These are hard limits for the container, so be sure there is enough headroom above what `docker stats` shows for your container. It will immediately halt if it hits `<MAXRAM>`. In general, keeping all cache and tmp filespace in RAM is preferable to disk I/O where possible.

-##### Check Storage Type
+### Step 4: Check your storage type

-Mounting a network share is a popular option for storing Recordings, but this can lead to reduced copy times and cause problems. Some users have found that using `NFS` instead of `SMB` considerably decreased the copy times and fixed the issue. It is also important to ensure that the network connection between the device running Frigate and the network share is stable and fast.
+Mounting a network share is a popular option for storing recordings, but it can lead to reduced copy times and cause problems. Some users have found that using `NFS` instead of `SMB` considerably decreased copy times and fixed the issue. It is also important to ensure that the network connection between the device running Frigate and the network share is stable and fast — a saturated or unreliable link will stall copies.

-##### Check mount options
+### Step 5: Check your mount options

-Some users found that mounting a drive via `fstab` with the `sync` option caused dramatically reduce performance and led to this issue. Using `async` instead greatly reduced copy times.
+Some users found that mounting a drive via `fstab` with the `sync` option dramatically reduced performance and led to this issue. Using `async` instead greatly reduced copy times.

-#### Copy Times < 1 second
+### Step 6: Rule out CPU load

-If the storage is working quickly then this error may be caused by CPU load on the machine being too high for Frigate to have the resources to keep up. Try temporarily shutting down other services to see if the issue improves.
+If the copy times are consistently under 1 second but you still see the warning, the machine's CPU load is likely too high for Frigate to have the resources to keep up. Try temporarily shutting down other services — and any resource-intensive Frigate features — to see if the issue improves.

 ## I see the message: WARNING : Too many unprocessed recording segments in cache for camera. This likely indicates an issue with the detect stream...

@@ -168,3 +274,40 @@ If none of the above apply, the issue may be a general resource constraint. Moni
 - **Storage space** — Verify you have free space on the Frigate storage volume (check the Storage page in the Frigate UI).

 Try temporarily disabling resource-intensive features like `genai` and `face_recognition` to see if the issue resolves. This can help isolate whether the detector is being starved of resources.
+
+## I see the message: ERROR : Error occurred when attempting to maintain recording cache
+
+This message means the recording maintainer hit an error while moving segments from the cache to disk. It is a **generic wrapper** — the actual cause is always logged on the **very next line**. Frigate usually recovers and keeps running, but any affected segments are lost, so it is worth resolving.
+
+:::warning
+
+Always read the line immediately following this message. `Error occurred when attempting to maintain recording cache` on its own tells you nothing; the exception on the next line — for example `[Errno 28] No space left on device` or `[Errno 17] File exists` — is the real problem.
+
+:::
+
+Because these are operating-system-level errors, they must be resolved on the **host**, not within Frigate's configuration. The most common underlying errors are below.
+
+### [Errno 28] No space left on device
+
+The filesystem Frigate is writing to is full. Things to check:
+
+- **The recordings volume is genuinely full.** Check free space on the host with `df -h` for the path mapped to `/media/frigate`, and review the **Storage** page in the Frigate UI.
+- **The disk shows free space but is still "full".** This usually means the filesystem has run out of **inodes** (check with `df -i`), or recordings are landing on a different, smaller filesystem than you expect because of an incorrect bind mount — see [The storage volume isn't mounted correctly](#the-storage-volume-isnt-mounted-correctly) above.
+- **`/tmp/cache` is full.** If you mounted `/tmp/cache` as a small `tmpfs`, a backlog of segments can fill it. Increase the tmpfs size, or address whatever is causing segments to pile up (see the [Too many unprocessed recording segments](#i-see-the-message-warning--too-many-unprocessed-recording-segments-in-cache-for-camera-this-likely-indicates-an-issue-with-the-detect-stream) section above).
+- **The host blocks writes before Frigate can purge.** On some systems (for example Unraid with a fill-up threshold), the host stops writes before Frigate's emergency cleanup can run. Leave more headroom on the volume, or lower your retention so Frigate purges sooner.
+
+### [Errno 17] File exists (with ffmpeg "Error writing trailer" or "unable to re-open output file")
+
+Errors like `[Errno 17] File exists: '/media/frigate/recordings/.../<camera>'`, often alongside ffmpeg errors such as `Unable to re-open ... output file for shifting data` or `Error writing trailer: No such file or directory`, are a hallmark of an **unreliable network share** (NFS or SMB). The mount is dropping, serving stale directory entries, or mishandling file locking.
+
+- Confirm the network connection to the NAS is stable and fast — an intermittent link produces these errors sporadically.
+- Prefer **NFS over SMB** for the recordings mount; several users have found NFS more reliable and faster.
+- Review your `fstab`/mount options for settings that hurt consistency or performance (see the `sync` vs `async` note in the [Unable to keep up with recording segments](#i-see-the-message-warning--unable-to-keep-up-with-recording-segments-in-cache-for-camera-keeping-the-5-most-recent-segments-out-of-6-and-discarding-the-rest) section above).
+- Enable `frigate.record.maintainer` debug logging to confirm whether the errors line up with the share becoming unavailable.
+
+### Errors referencing a camera you manually renamed or removed
+
+If the next-line error references a camera name that no longer exists in your config, orphaned data is left over from a rename or removal in a persistent `/tmp/cache` volume.
+
+- Using a `tmpfs` mount for `/tmp/cache` as recommended in the [installation docs](/frigate/installation#storage) prevents stale cache files under the old camera name from surviving a restart, which avoids this issue entirely.
+- If errors persist, stop Frigate and remove any leftover segments for the old camera name from `/tmp/cache`.