Troubleshooting#
This page provides troubleshooting steps for common issues. If you encounter a problem not listed here, check the GitHub Issues board or file a new ticket.
General#
Containers Not Starting#
Symptoms: One or more services fail to start or immediately exit.
Solution:
docker compose logs
Check the output for dependency errors (database not ready, missing .env variables, port conflicts).
Port Conflicts#
Symptoms: A service fails to bind to its port; address already in use.
Solution: Update the port variables in .env (for example, UI_HTTPS_PORT) and restart:
docker compose down
docker compose up -d
Backend Not Healthy#
Symptoms: docker compose ps shows vms-adapter-backend as unhealthy or restarting.
Solution:
docker compose logs vms-adapter-backend
Common causes:
Live Video Captioning or DL Streamer Vision application is not reachable at startup — start the Analytics App before VAP.
VMS_PLUGIN_DATABASE_URLis incorrect — verify the PostgreSQL connection string.A required environment variable is missing — check for
sys.exit(1)in the logs.
Config File Not Found#
Symptoms: The backend exits with FATAL: config file not found: /app/config/config.yaml.
Solution: config/config.yaml is generated, not shipped. Generate it for your VMS and apps,
then restart the backend:
./setup.sh --vms <vms> --apps <apps> # for example: --vms nx --apps ld,lvc
docker compose restart backend
setup.sh Refuses to Overwrite config.yaml#
Symptoms: setup.sh fails with config.yaml was not generated by setup.sh.
Cause: config/config.yaml was edited by hand or comes from an earlier release.
Solution: Move any custom settings into the matching vap-config.yaml fragment, then run
setup.sh with --force. The previous file is kept as config/config.yaml.bak.
Missing Variables Warning from setup.sh#
Symptoms: setup.sh prints set these variables in .env before starting VAP: ....
Solution: The listed variables are used by the selected VMS or apps and have no default. Set
them in .env. Variables of VMS and apps that you did not select are not checked or used.
Camera Discovery#
No Cameras Discovered from Nx Witness#
See the Nx Witness troubleshooting.
Live Video Captioning (LVC)#
Analytics Dashboard Shows an Error on Load#
Symptoms: The Analytics Engine panel shows an error when VAP first starts.
Cause: VAP fetches the LVC OpenAPI schema at startup. If LVC is not running, the schema fetch fails.
Solution: Start LVC before starting VAP, then restart the VAP backend:
docker compose restart vms-adapter-backend
Captions Not Appearing in the Dashboard#
Symptoms: A run is started but no captions appear in the caption overlay.
Checks:
Confirm the RTSP stream is reachable from the LVC
dlstreamer-pipeline-servercontainer.Check LVC logs:
docker compose logs dlstreamer-pipeline-server(in the LVC stack).Verify the SSE stream is connected: open
https://localhost:3443/v1/analytics-apps/live_captioning/results/streamin a browser.If running in a proxy network, add the RTSP stream IP to
no_proxy.
WebRTC Video Not Playing#
Symptoms: The live stream panel shows a black frame or connection failure.
Checks:
Verify
MEDIAMTX_URLin.envpoints to a reachable MediaMTX instance.Confirm
HOST_IPin the LVC.envis reachable from the browser client.Check firewall rules allow the WebRTC/WHIP port (
8889).
Model Dropdown Is Empty#
Symptoms: No models appear in the model selector in the dashboard.
Checks:
Ensure LVC’s
ov_models/directory contains at least one model with OpenVINO™ IR files.Restart the LVC stack so the service rescans the directory.
DL Streamer Vision (dls_vision) based app like Loitering Detection#
VAP Cannot Reach the DL Streamer Pipeline Server#
Symptoms: Starting a dls_vision run fails; backend logs show a connection error to DLS_VISION_HOST.
Checks:
Verify
DLS_VISION_HOSTandDLS_VISION_PORTin.envare correct.Confirm the DL Streamer Pipeline Server is running:
curl http://<DLS_VISION_HOST>:8080/pipelines.If
dls_visionruns on the same host as VAP, usehost.docker.internalforDLS_VISION_HOST.
No Bounding Boxes Appear in Nx Witness#
See the Nx Witness troubleshooting.
MQTT Messages Not Received#
Symptoms: MqttSubscriber does not forward detections; no analytics objects appear in Nx.
Checks:
Check the MQTT topic convention:
{metadata_topic_prefix}/{vms_name}:{camera_id}(default prefixobject_tracking), e.g.object_tracking/nx:abc123.Verify the
vms_namein the topic matches thenamefield of the VMS instance in itsvms_shim/<vms>/vap-config.yamlfragment.Inspect MQTT traffic using a tool like
mosquitto_sub:mosquitto_sub -h <MQTT_HOST> -t '#' -v
Database#
PostgreSQL Connection Refused#
Symptoms: Backend logs show could not connect to server or Connection refused on startup.
Checks:
Verify the
vms-adapter-postgrescontainer is healthy:docker compose ps vms-adapter-postgres.Check
PG_PASSWORDin.envmatches the value used to initialize the database.If you changed the password after the volume was created, remove the volume and restart:
docker compose down -v docker compose up -d