Skip to content

Troubleshooting Guide

This guide addresses common issues and provides steps for diagnostics and support.

🔧 Common Issues

Permission errors on Proxmox / Synology / QNAP

If you see PermissionError: [Errno 13] or could not create Unix socket, try uncommenting in docker-compose.yml:

security_opt:
  - seccomp:unconfined
  - apparmor:unconfined

As a last resort, use privileged: true on the affected service.

Weak or default SECRET_KEY warning

If you see critical warnings in the backend logs regarding SECRET_KEY or a persistent red security banner across the web interface:

  1. Check that SECRET_KEY in .env is not set to one of the default values and is at least 32 characters long.
  2. Generate a secure random key using openssl rand -hex 32.
  3. Update .env and restart the containers with docker compose down && docker compose up -d --build.
  4. To acknowledge a weak key during troubleshooting without blocking production warnings, you can set ALLOW_WEAK_SECRET=true in .env. Note that weak key diagnostics are strictly restricted to authenticated administrator sessions and are never leaked via public health endpoints.

Cameras not connecting

Verify the RTSP URL is reachable from inside the Docker container. The localhost addresses are blocked for security reasons — use the camera's actual LAN IP.

💡 Note on URL format: VibeNVR supports raw RTSP paths including double slashes (e.g., rtsp://ip:port//stream2). + +--- + +### 🔋 Battery / Wyze Camera Stability +Wyze V3 and some battery-powered cameras (Eufy, Reolink) can be sensitive to rapid RTSP connections. + +Recommended Settings: +1. RTSP Transport: Set to TCP in Camera Settings (Main & Sub stream). +2. Detection Mode: Use ONVIF Edge if supported, or ensure AI Master Switch is ON to allow the engine to use its adaptive sleep patterns. +3. NAL Parsing: VibeNVR automatically uses optimized NAL-unit parsing to handle the non-standard H.264 streams typical of these devices. + +---

Live View shows "Authentication Error" / 401

If you see an "AUTH ERROR" overlay, it might be a race condition during token load.

Solution: 1. Ensure you are running the latest version of VibeNVR. 2. Check camera credentials in Settings → Cameras. 3. VibeNVR automatically enters a 5-minute backoff period on persistent 401 errors to prevent IP bans.

🎥 MP4 Recordings crash or fallback to software encoding

If you notice that Passthrough recording isn't working (e.g. AI bounding boxes are burned into the video or CPU usage spikes), check the Engine logs for [Errno 22] Invalid argument from av.open.

Likely Cause: VibeNVR uses PyAV 15+ and FFmpeg 7+ for strict, high-performance RTSP packet demuxing. Some IP cameras send keyframes with missing temporal timestamps (dts/pts = None), which FFmpeg 7 strictly rejects when muxing into MP4 containers.

Solution: 1. VibeNVR automatically implements a stream normalization patch (recording_manager.py) that propagates the correct time_base and resets invalid None timestamps to 0 to prevent muxing crashes. 2. If the issue persists, ensure your camera's firmware is up-to-date and that its RTSP stream complies with H.264 standard temporal metadata. As a workaround, you can disable Passthrough and force software encoding.

🎥 MP4 Recordings Accumulate Duration (e.g. 1m, 2m, 3m) or Memory Leaks

If you observe that 1-minute segmented MP4 files progressively grow in length (e.g., the first file is 1 minute, the second is 2 minutes, the third is 3 minutes) and they start with the exact same repetitive footage, or if your container RAM usage grows indefinitely:

Likely Cause: - PyAV AVStream inheritance: The NVR's MP4 muxer was previously inheriting the global duration of the long-running live stream connection instead of creating independent segments. - RTSP Timestamp Jitter (Ring Buffer Poisoning): Some cameras (or stream loops) reset their internal PTS (Presentation Time Stamp) to 0. This caused the pre-buffer ring expiry logic to calculate negative durations, preventing old packets from ever being discarded.

Solution: VibeNVR v1.35.5+ fully mitigates these issues by replacing add_stream_from_template with manual stream initialization and by calculating ring buffer expirations using strictly monotonic OS-level time (time.time()). Ensure you are running the latest Engine container build.

🎥 Black Videos on Recording (Passthrough Enabled)

If you enable Passthrough recording and the camera outputs a raw Annex-B stream (common in Tapo, Foscam, Reolink, and generic OEM cameras), older versions of VibeNVR would generate unplayable MP4 files or force heavy CPU transcoding.

Solution: This is now handled automatically. As of the latest update, VibeNVR automatically detects Annex-B streams via their packet headers and seamlessly switches the recording container from .mp4 to .mkv (Matroska) on the fly. This guarantees you maintain 100% zero-CPU passthrough while generating standard-compliant files that play flawlessly in modern browsers.

[!WARNING] Incompatible Cameras If the saved .mkv video still results in a completely black screen (e.g., some generic non-compliant IP cameras), it means the camera's raw stream is missing fundamental data like keyframes or standard headers. In this extreme case, Passthrough is simply not compatible with your camera. You must manually disable Passthrough in the camera settings to force VibeNVR to decode and rebuild the stream completely.

⚡ Troubleshooting WebCodecs

⚡ Live View Falls Back to MJPEG unexpectedly

If you have an H.264 camera but the frontend displays JPEG Poll instead of WS / H.264 or MSE / H.264: 1. Verify Codec: Ensure the camera is actually outputting H.264. Browsers (and MSE) cannot natively decode H.265 (HEVC), so VibeNVR will automatically fallback to MJPEG for H.265 streams on HTTP. 2. Slow Startup: Some cheaper/slower cameras take a long time to send the first keyframe. VibeNVR waits up to 10 seconds for a decodable frame before falling back. Ensure your camera's I-Frame interval is not set too high (recommend 1x or 2x the FPS).

If you experience "black screens": 1. Ensure your browser supports WebCodecs API (Chrome/Edge 94+). 2. Check for Secure Context (HTTPS or localhost). 3. If the stream stalls, the frontend jitter buffer should smooth it out automatically.

🧠 High Memory Usage / OOM Errors

If VibeNVR containers are crashing due to memory exhaustion or your host RAM is saturated: 1. Resolution vs Buffers: High-resolution streams (1080p/4K) combined with large pre-capture buffers consume massive amounts of RAM. 2. Consult the Resource Optimization Guide for detailed RAM estimation formulas and tuning strategies (Passthrough, Sub-streams, Throttling).

🐢 High CPU Usage / UI Lag in Grid View

If the browser or host CPU spikes when viewing multiple cameras: 1. Enable Dual-Stream: Configure a low-resolution sub-stream for your cameras. the UI grid will automatically prioritize the sub-stream, saving massive amounts of bandwidth and decoding power. 2. Check FPS Throttle: Increase opt_live_view_fps_throttle in Global Settings to reduce the frequency of MJPEG fallback frames. 3. Hardware Offloading: Use a Coral TPU for AI detection to offload CPU inference. See the Resource Optimization Guide for more tips.

🐛 Reporting Bugs

If you encounter a bug, please open an issue on GitHub. Include a Diagnostic Bundle: 1. Log in as Admin. 2. Go to System Logs. 3. Click "Download Report". 4. Attach the .zip file to your GitHub issue.

💡 Tip: VibeNVR logs are now standardized with consistent timestamps across all components. When reviewing docker compose logs, you can easily correlate events between the Backend, Engine, and Frontend. Sensitive data (passwords, tokens) is automatically redacted.

If you encounter "No session cookie" errors or are repeatedly logged out: 1. Check COOKIE_SECURE: By default, it is set to auto. The system detects if you are on HTTP or HTTPS. 2. Local Access: If accessing via IP (e.g., http://192.168.1.50:8080), ensure you are using a modern browser. 3. Reverse Proxy: If you are behind a proxy (like Nginx Proxy Manager), ensure it correctly passes the X-Forwarded-Proto header. 4. Manual Override: If auto fails in your specific network setup, explicitly set COOKIE_SECURE=false in your .env file for local-only use.