From 168cbea9eaa04266c5a271ab865c884835ecae3b Mon Sep 17 00:00:00 2001 From: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com> Date: Wed, 22 Jul 2026 11:13:58 -0500 Subject: [PATCH] Docs tweaks (#23787) * docs fixes * backend tweaks * regenerate i18n * tweak genai * add config overrides section * add common errors * add suggestions for rebuilding a corrupt database --- docs/docs/configuration/advanced/reference.md | 16 +- docs/docs/configuration/advanced/system.md | 2 +- docs/docs/configuration/config.md | 5 +- docs/docs/configuration/config_overrides.md | 244 ++++++++++++++++++ .../state_classification.md | 6 +- docs/docs/configuration/genai/config.md | 131 ++++++---- docs/docs/configuration/genai/objects.md | 7 +- docs/docs/configuration/live.md | 2 +- docs/docs/configuration/semantic_search.md | 4 +- docs/docs/integrations/home-assistant.md | 2 +- docs/docs/integrations/mqtt.md | 2 +- docs/docs/troubleshooting/common_errors.md | 234 +++++++++++++++++ docs/sidebars.ts | 2 + frigate/config/config.py | 2 +- frigate/detectors/detector_config.py | 2 +- frigate/util/model.py | 2 +- web/public/locales/en/config/global.json | 4 +- 17 files changed, 593 insertions(+), 74 deletions(-) create mode 100644 docs/docs/configuration/config_overrides.md create mode 100644 docs/docs/troubleshooting/common_errors.md diff --git a/docs/docs/configuration/advanced/reference.md b/docs/docs/configuration/advanced/reference.md index 896ab2642b..e70eeeca83 100644 --- a/docs/docs/configuration/advanced/reference.md +++ b/docs/docs/configuration/advanced/reference.md @@ -11,6 +11,8 @@ It is not recommended to copy this full configuration file. Only specify values ::: +Sections marked `# NOTE: Can be overridden at the camera level` can be set globally and then adjusted per camera. See [Global and Camera-Level Configuration](../config_overrides.md) for how that works. + ```yaml mqtt: # Optional: Enable mqtt server (default: shown below) @@ -171,13 +173,14 @@ model: # Valid values are rgb, bgr, or yuv. (default: shown below) input_pixel_format: rgb # Required: Object detection model input tensor format - # Valid values are nhwc or nchw (default: shown below) + # Valid values are nhwc, nchw, hwnc, or hwcn (default: shown below) input_tensor: nhwc # Optional: Data type of the model input tensor # Valid values are float, float_denorm, or int (default: shown below) input_dtype: int - # Required: Object detection model type, currently only used with the OpenVINO detector - # Valid values are ssd, yolox, yolonas (default: shown below) + # Required: Object detection model architecture, used by detectors that support more + # than one model type (openvino, onnx, rknn, memryx, axengine, synaptics, and others) + # Valid values are ssd, yolox, yolonas, yolo-generic, rfdetr, dfine (default: shown below) model_type: ssd # Required: Label name modifications. These are merged into the standard labelmap. labelmap: @@ -468,8 +471,8 @@ review: detections: False # Optional: Activity Context Prompt to give context to the GenAI what activity is and is not suspicious. # It is important to be direct and detailed. See documentation for the default prompt structure. - activity_context_prompt: """Define what is and is not suspicious -""" + activity_context_prompt: | + Define what is and is not suspicious # Optional: Image source for GenAI (default: preview) # Options: "preview" (uses cached preview frames at ~180p) or "recordings" (extracts frames from recordings at 480p) # Using "recordings" provides better image quality but uses more tokens per image. @@ -813,7 +816,8 @@ classification: cameras: camera_name: # Required: Crop of image frame on this camera to run classification on - crop: [0, 180, 220, 400] + # [x1, y1, x2, y2] as decimals between 0 and 1, relative to the detect resolution + crop: [0.0, 0.25, 0.3, 0.85] # Optional: If classification should be run when motion is detected in the crop (default: shown below) motion: False # Optional: Interval to run classification on in seconds (default: shown below) diff --git a/docs/docs/configuration/advanced/system.md b/docs/docs/configuration/advanced/system.md index 28291efff7..c1ab568352 100644 --- a/docs/docs/configuration/advanced/system.md +++ b/docs/docs/configuration/advanced/system.md @@ -335,7 +335,7 @@ For example: ``` services: frigate: - image: blakeblackshear/frigate:latest + image: ghcr.io/blakeblackshear/frigate:stable environment: - FRIGATE_BASE_PATH=/frigate ``` diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md index edb6d0cd74..76458e4d36 100644 --- a/docs/docs/configuration/config.md +++ b/docs/docs/configuration/config.md @@ -20,7 +20,7 @@ Settings are organized into two scopes: - **Global configuration**: values under apply to every camera by default. This is where you set the baseline behavior for object detection, recording, snapshots, motion, and so on. - **Camera configuration**: values under apply to a single camera. Use the camera selector button at the top of these pages to choose which camera you are editing. -When a camera-level section is left untouched, the camera simply inherits the global values. Changing a value on a camera page **overrides** the global value for that camera only: the global setting and every other camera are unaffected. This mirrors how the YAML works, where a value set under `cameras.` takes precedence over the same value set at the top level. +When a camera-level section is left untouched, the camera simply inherits the global values. Changing a value on a camera page **overrides** the global value for that camera only: the global setting and every other camera are unaffected. This mirrors how the YAML works, where a value set under `cameras.` takes precedence over the same value set at the top level. See [Global and Camera-Level Configuration](./config_overrides.md) for the full details, including how lists and maps are handled and which settings must be enabled globally first. To undo an override and go back to inheriting from the parent scope, use the reset button at the bottom of the section: @@ -130,7 +130,8 @@ go2rtc: ```yaml genai: - api_key: "{FRIGATE_GENAI_API_KEY}" + my_provider: + api_key: "{FRIGATE_GENAI_API_KEY}" ``` ## Common configuration examples diff --git a/docs/docs/configuration/config_overrides.md b/docs/docs/configuration/config_overrides.md new file mode 100644 index 0000000000..61aa545f44 --- /dev/null +++ b/docs/docs/configuration/config_overrides.md @@ -0,0 +1,244 @@ +--- +id: config_overrides +title: Global and Camera-Level Configuration +--- + +import ConfigTabs from "@site/src/components/ConfigTabs"; +import TabItem from "@theme/TabItem"; +import NavPath from "@site/src/components/NavPath"; + +Most of Frigate's configuration can be set once for all cameras and then adjusted for individual cameras. The global value acts as the default for every camera, and any camera can override it. + +This page explains how that inheritance works. For a tour of the Settings UI itself, see [Frigate Configuration](./config.md). + +## The basics + +Set a value globally and every camera uses it. Set the same value on a camera and that camera uses its own value instead. + + + + +1. Navigate to and set **Detect FPS** to `5`. Every camera now detects at 5 fps. +2. Navigate to , select the `driveway` camera, and set **Detect FPS** to `10`. + +The `driveway` camera now detects at 10 fps. Every other camera still uses the global value of 5. + + + + +```yaml +detect: + fps: 5 # every camera detects at 5 fps + +cameras: + front_door: + ffmpeg: ... + driveway: + ffmpeg: ... + detect: + fps: 10 # except this one +``` + +`front_door` inherits `fps: 5`, and `driveway` uses `10`. + + + + +## Overrides apply per value, not per section + +Overriding one value in a section does not detach the rest of that section. Everything you don't set on the camera still comes from the global configuration. + + + + +If you set a camera's **Motion threshold** but leave **Contour area** alone, only the threshold is overridden. The contour area continues to follow , and changing it there still affects that camera. + +Open a section to see which values are overridden: the section header indicates how many fields differ from the global configuration. + + + + +```yaml +motion: + threshold: 30 + contour_area: 10 + +cameras: + driveway: + motion: + threshold: 40 +``` + +The `driveway` camera ends up with `threshold: 40` and `contour_area: 10`. Only the value you wrote was overridden. + + + + +## Returning a camera to the global value + + + + +A camera section that has its own values shows an **Overridden** badge. To remove the override and go back to inheriting, use the **Reset to Global** button at the bottom of the section. + + + + +Frigate treats a camera value as an override because it is written in the config file, not because it differs from the global value. Repeating the global value under a camera still creates an override: + +```yaml +snapshots: + enabled: true + +cameras: + driveway: + snapshots: + enabled: true # this is an override, even though it matches +``` + +If you later change the global `snapshots.enabled` to `false`, `driveway` keeps saving snapshots, because it has its own value. To make a camera follow the global value again, delete the key from the camera rather than setting it to match. + + + + +## Lists replace, maps merge + +This is the distinction that surprises people most. + +**Lists are replaced entirely.** A camera's list does not add to the global list, it takes its place. + + + + +The camera page shows the objects the camera is currently tracking, starting from the global list. Changing that selection under replaces the list for that camera, so make sure every object you want tracked is selected, not just the ones you are adding. + + + + +```yaml +objects: + track: + - person + - car + +cameras: + backyard: + objects: + track: + - dog # backyard tracks ONLY dog, not person or car +``` + +To track `dog` in addition to the global objects, list all of them on the camera. + + + + +An empty list is a valid override, and is the normal way to opt a camera out of something: + +```yaml +review: + alerts: + labels: + - person + +cameras: + street: + review: + alerts: + labels: [] # this camera never creates alerts +``` + +**Maps are merged key by key.** A camera can add an entry without redeclaring the others. + + + + +Adding a filter for one object under does not remove the filters inherited from . The camera keeps both. + + + + +```yaml +objects: + filters: + person: + min_area: 5000 + +cameras: + driveway: + objects: + filters: + car: + min_area: 10000 +``` + +The `driveway` camera ends up with both the `car` filter it defined and the `person` filter from the global configuration. + + + + +## Which settings can be overridden + +Most, but not all. The [full reference config](./advanced/reference.md) is the authoritative source: sections that support camera-level overrides are marked with the comment `# NOTE: Can be overridden at the camera level`. In the UI, a setting can be overridden if it appears under both and . + +A few things worth knowing beyond that: + +- Some sections are **global only** and have no camera-level equivalent, including `go2rtc`, `genai` providers, `classification`, `telemetry`, `camera_groups`, and `ui`. +- Some sections exist **only at the camera level**, such as `zones` and `onvif`. +- Some sections are **partially overridable**, meaning a camera accepts only a few of the keys available globally. `face_recognition`, `lpr`, and `audio_transcription` work this way, and the reference config notes which keys apply. + +## Enrichments that must be enabled globally first + +License plate recognition and face recognition are special: the global setting is not just a default, it is a switch that must be on before any camera can use the feature. Enabling one on a camera while it is disabled globally is a configuration error, and Frigate will refuse to start: + +``` +Camera driveway has lpr enabled but lpr is disabled at the global level of the config. You must enable lpr at the global level. +``` + +Enable the feature globally, then turn it off on the cameras that don't need it. + + + + +1. Navigate to and enable **LPR**. +2. Navigate to , select each camera that should not run LPR, and disable the **Enable LPR** toggle. + + + + +```yaml +lpr: + enabled: true + +cameras: + driveway: + ffmpeg: ... # inherits lpr, enabled + backyard: + ffmpeg: ... + lpr: + enabled: false # opted out +``` + + + + +:::note + +This applies only to `lpr` and `face_recognition`, because the global setting controls whether the supporting background process starts at all. Other features do not work this way. Audio transcription, for example, can be enabled on a single camera without being enabled globally. + +::: + +## Profiles + +[Profiles](./profiles.md) add a further layer on top of everything described above. A profile is a named set of camera overrides that you can switch on and off while Frigate is running, for example to change detection and recording behavior when you leave the house. + +Profiles are applied on top of a camera's already-resolved configuration, so a profile value wins over both the camera and the global value while that profile is active. Profiles cover a subset of the camera sections and do not modify your config file. + +## Summary + +- A camera inherits every value you don't set on it. +- Overriding one value does not detach the rest of the section. +- Writing a value on a camera overrides it, even if it matches the global value. Remove it to inherit again. +- Lists replace the global list. Maps merge into it. +- An empty list is an override, not an omission. +- `lpr` and `face_recognition` must be enabled globally before a camera can use them. diff --git a/docs/docs/configuration/custom_classification/state_classification.md b/docs/docs/configuration/custom_classification/state_classification.md index 7d479946bf..aea4742537 100644 --- a/docs/docs/configuration/custom_classification/state_classification.md +++ b/docs/docs/configuration/custom_classification/state_classification.md @@ -73,9 +73,13 @@ classification: interval: 10 # also run every N seconds (optional) cameras: front: - crop: [0, 180, 220, 400] + # [x1, y1, x2, y2] as decimals between 0 and 1, relative to the + # camera's detect resolution + crop: [0.0, 0.25, 0.3, 0.85] ``` +Crop coordinates are normalized: each value is a fraction of the camera's `detect` width or height, not a pixel value. Drawing the crop in the UI wizard writes these values for you. + An optional config, `save_attempts`, can be set as a key under the model name. This defines the number of classification attempts to save in the Recent Classifications tab. For state classification models, the default is 100. diff --git a/docs/docs/configuration/genai/config.md b/docs/docs/configuration/genai/config.md index d1da92c05f..d54f6a464e 100644 --- a/docs/docs/configuration/genai/config.md +++ b/docs/docs/configuration/genai/config.md @@ -9,9 +9,27 @@ import NavPath from "@site/src/components/NavPath"; ## Configuration -A Generative AI provider can be configured in the global config, which will make the Generative AI features available for use. There are currently 4 native providers available to integrate with Frigate. Other providers that support the OpenAI standard API can also be used. See the OpenAI-Compatible section below. +A Generative AI provider can be configured in the global config, which will make the Generative AI features available for use. There are currently 5 native providers available to integrate with Frigate. Other providers that support the OpenAI standard API can also be used. See the OpenAI-Compatible section below. -To use Generative AI, you must define a single provider at the global level of your Frigate configuration. If the provider you choose requires an API key, you may either directly paste it in your configuration, or store it in an environment variable prefixed with `FRIGATE_`. +`genai` is a map of named providers. Each key under `genai` is a name you choose, and its value is that provider's settings: + +```yaml +genai: + my_provider: # any name you like + provider: ollama + base_url: http://localhost:11434 + model: qwen3-vl:4b + roles: + - descriptions + - embeddings + - chat +``` + +The examples on this page all use `my_provider`, but the name is arbitrary and is only used to reference the provider elsewhere in the config (for example, `semantic_search.model`). + +Each provider handles one or more **roles**: `chat`, `descriptions`, and `embeddings`. A provider handles all three by default, and each role may be assigned to exactly one provider. Define a single provider if you want it to do everything, or split the roles across several providers using the `roles` option. + +If the provider you choose requires an API key, you may either directly paste it in your configuration, or store it in an environment variable prefixed with `FRIGATE_`. ## Local Providers @@ -85,11 +103,12 @@ All llama.cpp native options can be passed through `provider_options`, including ```yaml genai: - provider: llamacpp - base_url: http://localhost:8080 - model: your-model-name - provider_options: - context_size: 16000 # Optional, overrides the context size reported by the server. + my_provider: + provider: llamacpp + base_url: http://localhost:8080 + model: your-model-name + provider_options: + context_size: 16000 # Optional, overrides the context size reported by the server. ``` @@ -129,13 +148,14 @@ Note that Frigate will not automatically download the model you specify in your ```yaml genai: - provider: ollama - base_url: http://localhost:11434 - model: qwen3-vl:4b - provider_options: # other Ollama client options can be defined - keep_alive: -1 - options: - num_ctx: 8192 # make sure the context matches other services that are using ollama + my_provider: + provider: ollama + base_url: http://localhost:11434 + model: qwen3-vl:4b + provider_options: # other Ollama client options can be defined + keep_alive: -1 + options: + num_ctx: 8192 # make sure the context matches other services that are using ollama ``` @@ -151,11 +171,12 @@ For OpenAI-compatible servers (such as llama.cpp) that don't expose the configur ```yaml genai: - provider: openai - base_url: http://your-llama-server - model: your-model-name - provider_options: - context_size: 8192 # Specify the configured context size + my_provider: + provider: openai + base_url: http://your-llama-server + model: your-model-name + provider_options: + context_size: 8192 # Specify the configured context size ``` This ensures Frigate uses the correct context window size when generating prompts. @@ -178,10 +199,11 @@ This ensures Frigate uses the correct context window size when generating prompt ```yaml genai: - provider: openai - base_url: http://your-server:port - api_key: your-api-key # May not be required for local servers - model: your-model-name + my_provider: + provider: openai + base_url: http://your-server:port + api_key: your-api-key # May not be required for local servers + model: your-model-name ``` @@ -219,19 +241,21 @@ Ollama also supports [cloud models](https://ollama.com/cloud), where model infer ```yaml genai: - provider: ollama - base_url: http://localhost:11434 - model: cloud-model-name + my_provider: + provider: ollama + base_url: http://localhost:11434 + model: cloud-model-name ``` or when using Ollama Cloud directly ```yaml genai: - provider: ollama - base_url: https://ollama.com - model: cloud-model-name - api_key: your-api-key + my_provider: + provider: ollama + base_url: https://ollama.com + model: cloud-model-name + api_key: your-api-key ``` @@ -269,9 +293,10 @@ To start using Gemini, you must first get an API key from [Google AI Studio](htt ```yaml genai: - provider: gemini - api_key: "{FRIGATE_GEMINI_API_KEY}" - model: gemini-2.5-flash + my_provider: + provider: gemini + api_key: "{FRIGATE_GEMINI_API_KEY}" + model: gemini-2.5-flash ``` @@ -281,12 +306,13 @@ genai: To use a different Gemini-compatible API endpoint, set the `provider_options` with the `base_url` key to your provider's API URL. For example: -```yaml {4,5} +```yaml {5,6} genai: - provider: gemini - ... - provider_options: - base_url: https://... + my_provider: + provider: gemini + ... + provider_options: + base_url: https://... ``` Other HTTP options are available, see the [python-genai documentation](https://github.com/googleapis/python-genai). @@ -320,9 +346,10 @@ To start using OpenAI, you must first [create an API key](https://platform.opena ```yaml genai: - provider: openai - api_key: "{FRIGATE_OPENAI_API_KEY}" - model: gpt-4o + my_provider: + provider: openai + api_key: "{FRIGATE_OPENAI_API_KEY}" + model: gpt-4o ``` @@ -338,13 +365,14 @@ To use a different OpenAI-compatible API endpoint, set the `OPENAI_BASE_URL` env For OpenAI-compatible servers (such as llama.cpp) that don't expose the configured context size in the API response, you can manually specify the context size in `provider_options`: -```yaml {5,6} +```yaml {6,7} genai: - provider: openai - base_url: http://your-llama-server - model: your-model-name - provider_options: - context_size: 8192 # Specify the configured context size + my_provider: + provider: openai + base_url: http://your-llama-server + model: your-model-name + provider_options: + context_size: 8192 # Specify the configured context size ``` This ensures Frigate uses the correct context window size when generating prompts. @@ -379,10 +407,11 @@ To start using Azure OpenAI, you must first [create a resource](https://learn.mi ```yaml genai: - provider: azure_openai - base_url: https://instance.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview - model: gpt-5-mini - api_key: "{FRIGATE_OPENAI_API_KEY}" + my_provider: + provider: azure_openai + base_url: https://instance.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview + model: gpt-5-mini + api_key: "{FRIGATE_OPENAI_API_KEY}" ``` diff --git a/docs/docs/configuration/genai/objects.md b/docs/docs/configuration/genai/objects.md index eb8dadef53..7ad8004abe 100644 --- a/docs/docs/configuration/genai/objects.md +++ b/docs/docs/configuration/genai/objects.md @@ -52,9 +52,10 @@ You can define custom prompts at the global level and per-object type. To config ```yaml genai: - provider: ollama - base_url: http://localhost:11434 - model: qwen3-vl:8b-instruct + my_provider: + provider: ollama + base_url: http://localhost:11434 + model: qwen3-vl:8b-instruct objects: genai: diff --git a/docs/docs/configuration/live.md b/docs/docs/configuration/live.md index 5df70844c9..de10255e30 100644 --- a/docs/docs/configuration/live.md +++ b/docs/docs/configuration/live.md @@ -196,7 +196,7 @@ services: ::: -See [go2rtc WebRTC docs](https://github.com/AlexxIT/go2rtc/tree/v1.8.3#module-webrtc) for more information about this. +See [go2rtc WebRTC docs](https://github.com/AlexxIT/go2rtc/tree/v1.9.14#module-webrtc) for more information about this. ### Two way talk diff --git a/docs/docs/configuration/semantic_search.md b/docs/docs/configuration/semantic_search.md index c58b634fd8..30a60d505f 100644 --- a/docs/docs/configuration/semantic_search.md +++ b/docs/docs/configuration/semantic_search.md @@ -163,8 +163,8 @@ genai: model: your-model-name roles: - embeddings - - vision - - tools + - descriptions + - chat semantic_search: enabled: True diff --git a/docs/docs/integrations/home-assistant.md b/docs/docs/integrations/home-assistant.md index dd7d548047..f5ca05f1a4 100644 --- a/docs/docs/integrations/home-assistant.md +++ b/docs/docs/integrations/home-assistant.md @@ -281,7 +281,7 @@ For advanced usecases, this behavior can be changed with the [RTSP URL template](#options) option. When set, this string will override the default stream address that is derived from the default behavior described above. This option supports [jinja2 templates](https://jinja.palletsprojects.com/) and has the `camera` dict -variables from [Frigate API](../integrations/api) +variables from [Frigate API](/integrations/api/frigate-http-api) available for the template. Note that no Home Assistant state is available to the template, only the camera dict from Frigate. diff --git a/docs/docs/integrations/mqtt.md b/docs/docs/integrations/mqtt.md index e929ade300..775adef3ea 100644 --- a/docs/docs/integrations/mqtt.md +++ b/docs/docs/integrations/mqtt.md @@ -16,7 +16,7 @@ MQTT requires a network connection to your broker. This is typically local, but ### `frigate/available` Designed to be used as an availability topic with Home Assistant. Possible message are: -"online": published when Frigate is running (on startup) +"online": published once Frigate is running and has published its initial state. Note that this is published on every connection to the broker, so it is republished if the broker restarts or the connection drops and recovers, without Frigate itself restarting. "stopped": published when Frigate is stopped normally "offline": published automatically by the MQTT broker if Frigate disconnects unexpectedly (via MQTT Will Message) diff --git a/docs/docs/troubleshooting/common_errors.md b/docs/docs/troubleshooting/common_errors.md new file mode 100644 index 0000000000..982b333055 --- /dev/null +++ b/docs/docs/troubleshooting/common_errors.md @@ -0,0 +1,234 @@ +--- +id: common_errors +title: Common Error Messages +--- + +import FaqItem from "@site/src/components/FaqItem"; + +This page is an index of error messages you might see in Frigate's logs, what each one means, and where to go next. It is organized by the kind of problem, not by which component logged the message. + +Two things to know before you start: + +- **Many of these messages come from FFmpeg, go2rtc, GPU drivers, or the operating system, not from Frigate itself.** Frigate captures and re-logs their output, so the log level shown in the Frigate UI does not always reflect the original severity. +- **Wrapped errors put the real cause on the next line.** When Frigate logs a generic message like `Error occurred when attempting to maintain recording cache`, the actual exception is logged immediately after it. When a camera's FFmpeg process exits, Frigate logs `The following ffmpeg logs include the last 100 lines prior to exit` and dumps that camera's FFmpeg output. Always read those lines, they are where the answer usually is. + +## Camera connection and streams + + + +These are FFmpeg errors about reaching the camera (or the go2rtc restream). `Connection refused` and `No route to host` mean nothing is listening at that address or the host is unreachable; `401 Unauthorized` is wrong credentials; `404 Not Found` is a wrong stream path (or a `restream` input pointing at a go2rtc stream name that does not exist). A camera that has hit its concurrent-connection limit can also return `refused` or `401` on a URL that works in VLC. + +See [go2rtc troubleshooting](/troubleshooting/go2rtc#1-read-the-go2rtc-logs) for how to isolate the stream. + + + + + +FFmpeg is running but has stopped delivering video for 20 seconds, so Frigate's camera watchdog restarts it. The stream connected at least once, then went quiet: a camera reboot, a network drop, the camera evicting the connection, or a stalled decoder. If it repeats on a loop, the stream is unstable. + + + + + +The detect FFmpeg process exited on its own. This message is only the notification; the cause is in the 100 FFmpeg log lines Frigate dumps right after it (look for a `Failed to sync surface`, `Connection refused`, codec, or audio error in that block). Related watchdog messages include ` exceeded fps limit`, which means the camera is delivering frames faster than `detect.fps` (usually a camera whose real frame rate differs from what is configured). + + + + + +An FFmpeg message meaning the camera sent packets with out-of-order timestamps. Because recordings are copied without re-encoding, FFmpeg cannot fix them, and the segment muxer often splits early, producing one-second segments and a cache backlog. The usual cause is a camera "Smart Codec" / H.264+ / H.265+ mode or a camera clock that jumps. + +See [Recordings: segments are only 1 second long](/troubleshooting/recordings#segments-are-only-1-second-long). + + + + + +An FFmpeg message meaning RTP packets arrived out of sequence, which almost always means the stream is using UDP transport. Frigate's RTSP presets force TCP, so seeing this points at a custom `input_args`, `preset-rtsp-udp`, or a go2rtc source that is not using TCP. Switch to TCP unless your camera is [UDP-only](/configuration/camera_specific#udp-only-cameras). + + + + + +FFmpeg decoder messages meaning the received video bitstream was incomplete or damaged. A few of these at every stream start are normal (the decoder connected before the first keyframe) and Frigate discards them. A continuous stream of them means real packet loss, from Wi-Fi or a saturated link, an overloaded camera, or an FFmpeg restart loop caused by another problem. Fix the underlying instability rather than the message. + + + + + +An FFmpeg message meaning it probed the stream but never saw enough decodable video to determine the frame size, often because the probe window ended before the first keyframe on a long-GOP stream, or because the stream is not delivering usable video. If it is a Reolink HTTP stream, use `preset-http-reolink`, which raises the probe size for exactly this case. + + + +## Recording + + + +Frigate's record watchdog is restarting the record FFmpeg process because no valid segment has reached the cache. This means the record stream is not connecting or the segments are being rejected (see the audio-codec entry below). + +See [Recordings: the record stream isn't connecting](/troubleshooting/recordings#the-record-stream-isnt-connecting). + + + + + +A cached recording segment failed validation (no readable video stream) and was deleted. The most common cause is a segment that was truncated because the record FFmpeg process was killed mid-write, so this often appears alongside, and as a consequence of, the record-stream restarts above. A segment containing only audio triggers it too. + + + + + +Some camera audio codecs (G.711 variants such as `pcm_alaw` and `pcm_mulaw`) cannot be stored in an MP4 container, so segments never finalize even though live view works. + +See [Recordings: incompatible audio codec](/troubleshooting/recordings#incompatible-audio-codec-recordings-silently-fail-to-save) for the FFmpeg preset that transcodes the audio to AAC. + + + + + +A generic wrapper; the real exception is on the next log line. Frequently it is `[Errno 28] No space left on device` or `[Errno 17] File exists` on a network share. + +See [Recordings cache warnings and errors](/troubleshooting/recordings#i-see-the-message-error--error-occurred-when-attempting-to-maintain-recording-cache), which covers this message and the common `Errno` cases. + + + +## Hardware acceleration + + + +A VAAPI/QSV hardware frame-sync failure between FFmpeg and the GPU driver, not a Frigate bug. It usually appears when the detect stream is being scaled or decoded on the GPU. + +See [GPU: Failed to download frame: -5](/troubleshooting/gpu#failed-to-download-frame--5), which lists the fixes in order (switch VAAPI/QSV preset, change `LIBVA_DRIVER_NAME`, use an H.264 substream, match detect resolution and fps to the stream). + + + + + +Both mean the GPU ran out of decode surfaces: `No decoder surfaces left` is NVIDIA NVDEC, `Can't allocate a surface` is Intel QSV. This is surface-pool exhaustion, typically from too many concurrent hardware-decoded cameras on one GPU (consumer NVIDIA cards have a driver-enforced limit on simultaneous decode sessions). Reduce the number of cameras decoding on that GPU, decode some on the CPU, or move to hardware without the session cap. + + + + + +This comes from the NVIDIA container runtime while starting the container, not from Frigate, and the container never starts. The NVIDIA driver is not loaded on the host. Confirm `nvidia-smi` works on the host itself (not inside the container) before troubleshooting Frigate. In a VM or LXC, the driver must be available inside the guest. See [Hardware: Nvidia GPU](/configuration/hardware_acceleration_video). + + + +## Detectors and models + + + +The process was killed by the CPU for executing an unsupported instruction. There are two distinct causes in Frigate: + +- **A Coral EdgeTPU** on a newer kernel with an outdated gasket driver. See [EdgeTPU: Illegal instruction](/troubleshooting/edgetpu#attempting-to-load-tpu-as-pci--fatal-python-error-illegal-instruction). +- **A CPU without AVX/AVX2**, when enabling semantic search, face recognition, license plate recognition, classification, or audio transcription. These features use libraries compiled with AVX and crash immediately on CPUs that lack it (commonly Intel Celeron/Pentium before the 2020 Tiger Lake generation). See the [CPU requirements](/frigate/planning_setup#cpu). + + + + + +ONNX Runtime could not parse the model file. The file exists but its contents are not a valid ONNX model, usually a corrupted or interrupted download in `model_cache`, or the wrong file pointed at by `model.path`. Delete the cached model file so Frigate re-downloads it, and confirm `model.path` points at an actual `.onnx` model. See [ONNX detector configuration](/configuration/object_detectors#onnx). + + + + + +ONNX Runtime CUDA errors. `999` (`cudaErrorUnknown`) is a general, unrecoverable CUDA context failure, usually a driver/runtime version mismatch between the host and the container or a GPU in a bad state. `901` is a CUDA-graph capture error, which points at a custom model whose operations are not capture-safe. For `999`, align the host driver with the container's CUDA version and confirm the GPU is healthy. + + + + + +OpenVINO could not find the configured device (usually `GPU` or `NPU`). Most often the `/dev/dri` render node is not passed into the container, or the wrong render node is mapped when an iGPU and a discrete GPU coexist. + +See [GPU: no supported devices found](/troubleshooting/gpu#cant-get-optimization_capabilities-property-as-no-supported-devices-found). + + + +## Memory and storage + + + +Frigate ran out of shared memory (`/dev/shm`). The container's `shm_size` is too small for the number and resolution of your detect streams, or you added cameras after startup without increasing it. + +See [Calculating required shm-size](/frigate/installation#calculating-required-shm-size). If you cannot increase `shm_size`, lowering the `SHM_MAX_FRAMES` environment variable reduces how many frames Frigate buffers per camera. + + + + + +A filesystem is full: the recordings volume (`/media/frigate`), the cache tmpfs (`/tmp/cache`), or `/dev/shm`. Check which one, and note that inode exhaustion can produce this while `df -h` still shows free space. + +See [Recordings: No space left on device](/troubleshooting/recordings#i-see-the-message-error--error-occurred-when-attempting-to-maintain-recording-cache). + + + + + +A silent exit is usually the host or container out-of-memory killer. Because `/dev/shm` and `/tmp/cache` are memory-backed, they count against the container's memory limit, so aggressive shm or cache sizing can trigger it. Give the container more memory, or reduce shm/cache sizing, and check the host's OOM messages (`dmesg`). + + + +## Database + + + +SQLite could not acquire the write lock. Frigate's timeout already scales with camera count, so under normal local-disk operation this essentially only happens when the database is on a network share (SMB/NFS), where file locking is unreliable, or when two instances point at the same file. + +See [Database is locked](/troubleshooting/faqs#error-database-is-locked). + + + + + +The SQLite database file is corrupted, typically after hard power loss, a network-share database, or a filesystem with unsafe write semantics. Frigate does not repair it automatically, but the database can usually be recovered by hand. + +**Stop Frigate first**, then work on the database file directly (by default `/config/frigate.db`). Start by checking what is actually wrong: + +```bash +sqlite3 frigate.db "PRAGMA integrity_check;" +``` + +If the only problems reported are index-related (lines such as `row 14 missing from index recordings_path` or `non-unique entry in index ...`), rebuilding the indexes is usually enough and is the least destructive fix: + +```bash +sqlite3 frigate.db "REINDEX;" +``` + +If the integrity check reports page or byte-level corruption instead (for example `Multiple uses for byte 2706 of page 142272`), dump the readable contents into a new database: + +```bash +# dump what can still be read +sqlite3 frigate.db .dump > frigate.dump + +# keep the corrupt file, then rebuild from the dump +mv frigate.db frigate.db.bak +cat frigate.dump | sqlite3 frigate.db + +# confirm the rebuilt database is clean, this should print "ok" +sqlite3 frigate.db "PRAGMA integrity_check;" +``` + +Rows stored in the corrupted pages cannot be recovered, so expect to lose some tracked objects, review items, or thumbnails. Recordings themselves are files on disk and are not affected. + +As a last resort, stop Frigate, delete `frigate.db`, and restart. Frigate recreates it, but existing recordings lose all of their metadata. If a `backup.db` exists next to your database, Frigate wrote it before the last schema migration and restoring it recovers everything up to that point. + +Repeat corruption usually points at the underlying storage: move the database off a network share, and on Raspberry Pi check power delivery and the SD card or SSD. + + + +## Startup and web access + + + +When your config fails validation at startup, Frigate prints the validation errors (with line numbers), then starts in **safe mode**: a minimal configuration with no cameras and MQTT disabled, so the UI stays reachable. In safe mode the only available page is the Config Editor, which shows the validation errors so you can fix them, then save and restart. Note that recording retention and storage cleanup do **not** run while in safe mode, so do not leave a low-disk system sitting in it. + +`Unable to start Frigate in safe mode` means even the minimal config failed, which points at an error in your `auth`, `proxy`, or `database` section, or a config file that is not valid YAML at all. Safe mode is not sticky; fix the config and restart and Frigate returns to normal. + + + + + +The web server is up but the Frigate backend (port 5001) is not answering yet. By far the most common reason is that the page was loaded during startup: the API binds last, after database migrations (which can take minutes on a large database), model downloads, and process startup, while the web server is already serving. Wait for startup to finish. If it persists, the backend has failed to start, and the reason is earlier in the logs. This also explains a `connection refused to 127.0.0.1:5001` seen while loading `/ws`, because every authenticated request first makes an auth subrequest to that port. + + diff --git a/docs/sidebars.ts b/docs/sidebars.ts index ce6c41c133..4c656df8c2 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -30,6 +30,7 @@ const sidebars: SidebarsConfig = { ], Configuration: [ "configuration/config", + "configuration/config_overrides", { type: "category", label: "Detectors", @@ -165,6 +166,7 @@ const sidebars: SidebarsConfig = { ], Troubleshooting: [ "troubleshooting/faqs", + "troubleshooting/common_errors", "troubleshooting/go2rtc", "troubleshooting/recordings", "troubleshooting/dummy-camera", diff --git a/frigate/config/config.py b/frigate/config/config.py index b450d26e91..470ce15a2a 100644 --- a/frigate/config/config.py +++ b/frigate/config/config.py @@ -640,7 +640,7 @@ class FrigateConfig(FrigateBaseModel): # set notifications state self.notifications.enabled_in_config = self.notifications.enabled - # validate genai: each role (tools, vision, embeddings) at most once + # validate genai: each role (chat, descriptions, embeddings) at most once role_to_name: dict[GenAIRoleEnum, str] = {} for name, genai_cfg in self.genai.items(): for role in genai_cfg.roles: diff --git a/frigate/detectors/detector_config.py b/frigate/detectors/detector_config.py index 788fb58a79..52d75ff8f7 100644 --- a/frigate/detectors/detector_config.py +++ b/frigate/detectors/detector_config.py @@ -93,7 +93,7 @@ class ModelConfig(BaseModel): model_type: ModelTypeEnum = Field( default=ModelTypeEnum.ssd, title="Object Detection Model Type", - description="Detector model architecture type (ssd, yolox, yolonas) used by some detectors for optimization.", + description="Detector model architecture type (ssd, yolox, yolonas, yolo-generic, rfdetr, dfine) used by some detectors for optimization.", ) _merged_labelmap: dict[int, str] | None = PrivateAttr() _colormap: dict[int, tuple[int, int, int]] = PrivateAttr() diff --git a/frigate/util/model.py b/frigate/util/model.py index 338303e2d7..19e4f68f1d 100644 --- a/frigate/util/model.py +++ b/frigate/util/model.py @@ -326,7 +326,7 @@ def get_ort_providers( { "device_id": device_id, "trt_fp16_enable": requires_fp16 - and os.environ.get("USE_FP_16", "True") != "False", + and os.environ.get("USE_FP16", "True") != "False", "trt_timing_cache_enable": True, "trt_engine_cache_enable": True, "trt_timing_cache_path": os.path.join( diff --git a/web/public/locales/en/config/global.json b/web/public/locales/en/config/global.json index e3b7c65c68..9e3a71b7a8 100644 --- a/web/public/locales/en/config/global.json +++ b/web/public/locales/en/config/global.json @@ -322,7 +322,7 @@ }, "model_type": { "label": "Object Detection Model Type", - "description": "Detector model architecture type (ssd, yolox, yolonas) used by some detectors for optimization." + "description": "Detector model architecture type (ssd, yolox, yolonas, yolo-generic, rfdetr, dfine) used by some detectors for optimization." } }, "model_path": { @@ -495,7 +495,7 @@ }, "model_type": { "label": "Object Detection Model Type", - "description": "Detector model architecture type (ssd, yolox, yolonas) used by some detectors for optimization." + "description": "Detector model architecture type (ssd, yolox, yolonas, yolo-generic, rfdetr, dfine) used by some detectors for optimization." } }, "genai": {