VOD event endpoint returns 404 when requested immediately after event creation (race condition)

[flex420]

Checklist

• I have updated to the latest available Frigate version.
• I have cleared the cache of my browser.
• I have tried a different browser to see if it is related to my browser.
• I have tried reproducing the issue in incognito mode to rule out problems with any third party extensions or plugins I have installed.
• I have asked the AI at https://docs.frigate.video about my issue.

Describe the problem you are having

The VOD event endpoint /vod/event/{id}/master.m3u8 returns HTTP 404 when requested within approximately 5-10 seconds after event creation.

When Frigate creates a new event (e.g., person detected), it publishes the event via MQTT immediately. However, the recording segments for that event are not yet committed/indexed at that point. Any client requesting the VOD endpoint during this window receives a 404 error.

This is particularly problematic for Home Assistant notification blueprints (e.g., SgtBatten/HA-blueprints Stable.yaml) that generate push notifications with video preview URLs immediately upon receiving the MQTT event. The notification links to /api/frigate/notifications/{id}/{camera}/master.m3u8, which proxies to the VOD endpoint. Since the notification arrives within 1-5 seconds of event creation, the video is never available when the user taps the notification.

Expected behavior: The VOD endpoint should either wait for segments to become available (with a reasonable timeout), return a proper 'pending' status, or the event creation should be deferred until at least one segment is committed.

Actual behavior: The endpoint returns 404, and the video never becomes available through the notification link (users must manually navigate to the Frigate UI to view the recording).

Steps to reproduce

1. Set up Frigate v0.17.0 with recording enabled for a camera
2. Configure a Home Assistant notification automation that triggers on Frigate events (e.g., using SgtBatten/HA-blueprints Stable.yaml)
3. The automation subscribes to frigate/events MQTT topic and fires immediately on event creation
4. The notification includes a video URL: /api/frigate/notifications/{event_id}/{camera}/master.m3u8
5. Trigger a detection event (e.g., person walks in front of camera)
6. Tap the push notification within 1-10 seconds of receiving it
7. The video URL returns HTTP 404 or 454 because recording segments are not yet committed
8. Wait 15+ seconds and request the same URL - it now works correctly

The race condition window appears to be approximately 5-10 seconds after event creation.

Version

0.17.0-f0d69f7

In which browser(s) are you experiencing the issue with?

N/A - This is a backend API issue, not browser-specific

Frigate config file

version: 0.17-0

mqtt:
  host: 10.10.10.10
  port: 1883

detectors:
  coral:
    type: edgetpu
    device: usb
  cpu_fallback:
    type: cpu
    num_threads: 4

go2rtc:
  streams:
    eingang:
      - rtsp://admin:password@10.10.10.156:554/Streaming/Channels/101

cameras:
  eingang:
    ffmpeg:
      inputs:
        - path: rtsp://127.0.0.1:8554/eingang
          roles: [detect, record]
    detect:
      width: 2688
      height: 1520
      fps: 10
    objects:
      track: [person, dog]
    recording:
      enabled: true
      retain:
        days: 14
        mode: motion
      events:
        retain:
          default: 30
          mode: active_objects

docker-compose file or Docker CLI command

Docker run on Unraid (via Community Applications template):

docker run -d --name='frigate' \
  --privileged \
  -e TZ="Europe/Berlin" \
  -p 5000:5000 -p 8554:8554 -p 8555:8555/tcp -p 8555:8555/udp \
  -v /mnt/cache/appdata/frigate:/config \
  -v /mnt/poolboy/frigate:/media/frigate \
  --device /dev/bus/usb:/dev/bus/usb \
  --mount type=tmpfs,target=/tmp/cache,tmpfs-size=1000000000 \
  --shm-size=256m \
  ghcr.io/blakeblackshear/frigate:0.17.0

Relevant Frigate log output

No specific error logs - the issue is a timing/race condition, not a crash.
When requesting /vod/event/{id}/master.m3u8 within ~5-10 seconds of event creation,
the endpoint returns HTTP 404 silently. No error is logged on the Frigate side because
the recording segments simply haven't been committed to the database yet.

After the segments are committed (typically 10+ seconds after event creation),
the same endpoint returns 200 OK with valid HLS playlist data.

Relevant go2rtc log output

N/A - go2rtc is functioning correctly. The issue is in the VOD/recording segment indexing pipeline, not in the streaming layer.

Operating system

UNRAID

Install method

Docker CLI

Network connection

Wired

Camera make and model

HiKVision DS-2CD2346G2-IU

Screenshots of the Frigate UI's System metrics pages

N/A - Backend API issue, not a UI rendering problem.

Any other information that may be helpful

This issue particularly impacts the Home Assistant notification ecosystem. The SgtBatten/HA-blueprints Stable.yaml blueprint (widely used) generates push notifications with video URLs immediately upon MQTT event receipt. Since the MQTT event fires before recording segments are committed, the video URL is always broken when tapped.

Additionally, the event thumbnail/preview images also intermittently return HTTP 404 and HTTP 454 status errors, likely caused by the same race condition where the recording segments and associated media files are not yet available when requested immediately after event creation.

Environment: Unraid 7.0.0, Frigate 0.17.0 Docker, Coral USB Edge TPU on USB 3.0, HiKVision camera via go2rtc RTSP restream.

[inkeep-ai-assistant[bot]]

You've identified a timing issue where the /vod/event/{event_id} endpoint returns 404 when requested immediately after event creation, before recording segments are committed.

The VOD event endpoint returns an HLS playlist for the specified event(1)(2). According to the API documentation, you append /master.m3u8 or /index.m3u8 for HLS playback(1)(2). The endpoint also accepts an optional padding query parameter to apply padding to the VOD(1)(2).

The race condition you're experiencing occurs because Frigate publishes MQTT events immediately when objects are tracked, but the recording segments may not yet be available. The frigate/events MQTT topic publishes messages for each changed tracked object, with the first message published when the tracked object is no longer marked as a false positive(3). However, the has_clip field in the MQTT payload indicates whether a clip is available yet(3).

Workaround approach:

Monitor the has_clip field in the MQTT event payload before requesting the VOD endpoint. The MQTT event message includes:

"has_clip": false

This field updates to true once recording segments are available(3). You could modify your Home Assistant automation to wait for an update message where has_clip is true before generating the notification URL.

Alternative consideration:

The annotation_offset configuration under detect allows you to offset detect annotations by milliseconds to account for latency between recording and the detect process(4). While this addresses timeline alignment rather than segment availability, it demonstrates that Frigate acknowledges timing differences between detection and recording streams(4).

The documentation doesn't specify a built-in delay or retry mechanism for the VOD endpoint when segments aren't yet available. Your observation about the 5-10 second window aligns with typical segment duration and commit intervals in video recording systems.

For immediate notification use cases, you may need to implement client-side retry logic or delay notification generation until the has_clip field confirms availability in subsequent MQTT updates.

📚 Sources:

1. GET /vod/event/{event_id}
2. Vod Event
3. MQTT
4. Full Reference Config

---

Have another question? Just tag @inkeep.

[hawkeye217]

The AI is correct, this is expected behavior and not a bug. Frigate reports tracked object events using the stream defined by the detect role. When you define a separate stream with the record role, Frigate processes footage from this stream in 10 second chunks. Once this data is written, then the VOD endpoint should return a successful result.

[hawkeye217]

Since you're using the sgtbatten blueprint, the recommendation is to base notifications on the reviews topic, rather than events. If you want to continue to use events, the has_clip property is the correct one you'll want to filter on.