Troubleshooting#
This page provides troubleshooting steps, FAQs, and resources to help you resolve common issues. If you encounter any problems with the application not addressed here, check the GitHub Issues board. Feel free to file new tickets there (after learning about the guidelines for Contributing).
Troubleshooting Steps#
Changing the Host IP Address
If you need to use a specific Host IP address instead of the one automatically detected during installation, you can explicitly provide it using the following command. Replace
<HOST_IP>with your desired IP address:./install.sh loitering-detection <HOST_IP>
Example:
./install.sh loitering-detection 192.168.1.100
If you use the Console UI, use
loitering-detection-uiinstead:./install.sh loitering-detection-ui <HOST_IP>
Containers Not Starting:
Check the Docker logs for errors:
docker ps -a docker logs <CONTAINER_ID>
Failed Service Deployment:
If unable to deploy services successfully due to proxy issues, ensure the proxy is configured in the
~/.docker/config.json:{ "proxies": { "default": { "httpProxy": "http://your-proxy:port", "httpsProxy": "https://your-proxy:port", "noProxy": "localhost,127.0.0.1" } } }
After editing the file, restart docker:
sudo systemctl daemon-reload sudo systemctl restart docker
Video stream not displaying on Grafana UI
If you do not see the video stream because of a URL issue, then ensure that
WEBRTC_URLin Grafana has:# When Grafana is opened on https://localhost/grafana https://localhost/mediamtx/ # When Grafana is opened on https://<HOST_IP>/grafana https://<HOST_IP>/mediamtx/
Resolving Time Sync Issues in Prometheus
If you see the following warning in Prometheus, it indicates a time sync issue.
Warning: Error fetching server time: Detected xxx.xxx seconds time difference between your browser and the server.
You can follow the steps below to synchronize system time using NTP.
Install systemd-timesyncd if not already installed:
sudo apt install systemd-timesyncd
Check service status:
systemctl status systemd-timesyncd
Configure an NTP server (if behind a corporate proxy):
sudo nano /etc/systemd/timesyncd.conf
Add:
[Time] NTP=corp.intel.com
Replace
corp.intel.comwith a different ntp server that is supported on your network.Restart the service:
sudo systemctl restart systemd-timesyncd
Verify the status:
systemctl status systemd-timesyncd
This should resolve the time discrepancy in Prometheus.
Troubleshooting the Console UI#
See Use the Console UI for normal usage; the issues below are specific to it.
Console UI not reflecting a code change
The Console UI service bind-mounts
console-addon/consoledirectly (no build step, no custom image - it reusesdlstreamer-pipeline-server’s own image, which already has the Python packages the console needs), so a source edit only needs a restart, not a rebuild:
docker compose restart console
No bounding boxes on a stream
Detection runs on the full frame and every detected object gets a box regardless of zone (see How detection and zones interact), so a missing box means the model did not detect that object that frame (confidence below the pipeline’s threshold), not a zone restriction. Check the stream’s raw MQTT topic to confirm, or try different model for better recall on some object types/angles.
An object is in the zone outline but never appears in the table below it
The table only lists objects
gvaanalyticshas matched to that zone, which depends onevaluation-point=bottom-center(the object’s bottom-center point, not its whole box, must be inside the zone polygon) - an object whose box overlaps the zone but whose feet/base are still outside it will not match yet. Widen or reposition the zone if the area you care about needs to catch objects earlier.
Zone edits not taking effect
gvaanalyticscannot update a zone on a running pipeline, so Apply zone to live streams always restarts every live stream — expect a brief reconnect of each video panel.
Pipeline start fails with
400 ... BAD REQUEST, or a stream connects but never shows video or detections (any device, including GPU)Most likely cause: a proxy having a bad moment during
install.shcan return its own HTML error page (e.g. “504 Gateway Timeout”) with an HTTP 200 status -curltreats that as a successful download, silently leaving an HTML file in place of a real model or video file. Check for this first:file loitering-detection/src/dlstreamer-pipeline-server/videos/*.mp4 \ loitering-detection/src/dlstreamer-pipeline-server/models/intel/*/*.json \ loitering-detection/src/dlstreamer-pipeline-server/models/intel/*/FP16/*
Any result reported as
HTML documentinstead of a video/model format confirms this - every device fails identically on corrupted input, so this is not a DEVICE-specific problem. Re-runinstall.shto redownload, then restart the pipeline server so it drops any model-instance-id it already marked broken from the earlier corrupted file:docker compose up -d --force-recreate dlstreamer-pipeline-server
Less common cause: DL Streamer caches a loaded model against its
model-instance-id; if a pipeline using that id is ever stopped uncleanly, a shared id can leave the cache entry wedged so every later launch reusing it silently stalls. The Console UI andsample_start.shboth generate a unique id per launch, so this should no longer happen in normal use. The same restart command above clears this too.If it recurs reliably for a specific model/device combination even with valid files, check the pipeline server’s logs for errors around that model’s load, since that points at a model or device-compatibility problem rather than either cause above.
GPU utilization always shows “n/a” even while a GPU stream is running
The gauge reads Prometheus’s
qmmd_gpu_engine_utilization_ratiocompute-engine series, whose engine label varies by GPU generation/qmassa version (ccson some,computeon others). If it is still n/a after upgrading to a version with both labels recognized, confirm Prometheus actually has GPU series at all:docker exec ui-console curl -sk 'http://prometheus:9090/prometheus/api/v1/query?query=qmmd_gpu_engine_utilization_ratio'
An empty
resultarray means the metrics pipeline itself (metrics-manager’sqmassa) is not reporting for this GPU, not a Console UI bug - checkdocker logs metrics-manager.