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_URL is 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-server container.

  • 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/stream in 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_URL in .env points to a reachable MediaMTX instance.

  • Confirm HOST_IP in the LVC .env is 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_HOST and DLS_VISION_PORT in .env are correct.

  • Confirm the DL Streamer Pipeline Server is running: curl http://<DLS_VISION_HOST>:8080/pipelines.

  • If dls_vision runs on the same host as VAP, use host.docker.internal for DLS_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 prefix object_tracking), e.g. object_tracking/nx:abc123.

  • Verify the vms_name in the topic matches the name field of the VMS instance in its vms_shim/<vms>/vap-config.yaml fragment.

  • 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-postgres container is healthy: docker compose ps vms-adapter-postgres.

  • Check PG_PASSWORD in .env matches 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
    

Supporting Resources#