# Troubleshooting This page provides troubleshooting steps for common issues. If you encounter a problem not listed here, check the [GitHub Issues](https://github.com/open-edge-platform/metro-ai-suite/issues) board or file a new ticket. ## General ### Containers Not Starting **Symptoms**: One or more services fail to start or immediately exit. **Solution**: ```bash 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: ```bash docker compose down docker compose up -d ``` ### Backend Not Healthy **Symptoms**: `docker compose ps` shows `vms-adapter-backend` as unhealthy or restarting. **Solution**: ```bash 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: ```bash ./setup.sh --vms --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](./how-to-guides/integrations/nx-witness/reference.md#vap-and-nx-witness). --- ## 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: ```bash 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://: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](./how-to-guides/integrations/nx-witness/reference.md#pipeline-and-detections). ### 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//vap-config.yaml` fragment. - Inspect MQTT traffic using a tool like `mosquitto_sub`: ```bash mosquitto_sub -h -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: ```bash docker compose down -v docker compose up -d ``` --- ## Supporting Resources - [Get Started](./get-started.md) - [GitHub Issues](https://github.com/open-edge-platform/metro-ai-suite/issues) - [Docker Compose Documentation](https://docs.docker.com/compose/)