Troubleshooting

This section covers common issues encountered when operating Meridian VMS and provides diagnostic steps and solutions for each.

Common Issues

Camera Shows Offline But Is Reachable

Symptoms: The camera appears as “offline” in the dashboard or live view, but you can access its web interface and RTSP stream directly.

Likely causes:

Stream relay failure — The stream relay on the recording server may have crashed or failed to establish the RTSP connection to the camera. Check the MediaMTX logs:
Terminal window
```
sudo journalctl -u meridian-mediamtx -f
```
Sub-stream unavailability — If the camera is configured to use a sub-stream for detection or live view and the sub-stream is not available (some cameras disable the sub-stream by default), the relay will fail. Verify the sub-stream URL is valid or switch to main-stream only.
Heartbeat timeout — The recording server may not be sending heartbeats. Check the recorder daemon is running and the MQTT connection is active:
Terminal window
```
sudo systemctl status meridian-recorder
sudo journalctl -u meridian-recorder --since "5 minutes ago"
```
Network connectivity — Verify the recording server can reach the camera on the RTSP port:
Terminal window
```
ffprobe -rtsp_transport tcp rtsp://{camera_ip}:{port}/stream1
```

Recording Process Exit Code 234

Symptoms: Recording processes exit repeatedly with code 234. Recorder logs show "codec parameters not found" or "could not find codec parameters".

Cause: The recording engine cannot determine the codec parameters from the RTSP stream within the default analysis duration. This is common with cameras that have long keyframe intervals or non-standard stream configurations.

Solution: The recorder daemon automatically applies an increased analysis window for problematic streams. If the issue persists:

Verify the camera’s stream settings — reduce the keyframe interval (GOP size) to 1-2 seconds
Ensure the camera is outputting a supported codec (H.264 or H.265)
Check that the RTSP URL is correct and the stream is accessible

HLS bufferAppendError in Browser

Symptoms: Live view shows a black screen with console errors mentioning bufferAppendError or fragParsingError.

Cause: Certain camera manufacturers (notably Uniview) periodically change SPS/PPS parameters mid-stream. Chrome’s Media Source Extensions (MSE) cannot handle these changes.

Solution: This is a known browser limitation. Meridian VMS addresses it in two ways:

Live view: Use WebRTC instead of HLS for live streaming. WebRTC handles SPS/PPS changes natively. Meridian VMS defaults to WebRTC for all live views.
Event clips: Event clips are normalised for universal browser compatibility before delivery.

See Video Troubleshooting for more details on codec-related issues.

Database Connection Issues

Symptoms: API requests fail with timeout errors or connection-related messages. Common in deployments with many concurrent streams and active detection.

Cause: The database connection pool may be exhausted when too many concurrent operations are in flight. This can happen with large camera counts (100+) when heartbeats, segment indexing, and event writes all compete for connections.

Solution:

Check the database service is running and healthy
Review the management server logs for connection errors: sudo journalctl -u meridian-management -f
For large deployments (200+ cameras), consider increasing database connection limits — contact support for guidance

High CPU from Stream Relay

Symptoms: The MediaMTX process consumes excessive CPU, especially with many cameras.

Cause: If HLS remuxing is enabled, it forces continuous HLS segment generation for all streams, even when no one is watching. This is unnecessary when WebRTC is used for live viewing.

Solution: Disable HLS remuxing in the stream relay configuration if WebRTC is the primary live view protocol. This ensures HLS segments are only generated on demand, significantly reducing CPU usage on recording servers with many camera streams.

Topic	Description
Logs	Accessing and interpreting service logs for management, recorder, and MediaMTX
Video & Codec Issues	H.265 support, SPS/PPS issues, event clip processing, and sub-stream fallback