Troubleshooting#

This article contains troubleshooting steps for known issues. If you encounter a problem not listed here, check the GitHub Issues board or file a new ticket after reviewing the Contributing guidelines.

1. Build Fails During make build#

Issue

make build exits with an error during Docker image construction.

Reason

Docker Engine or Docker Compose is not installed, not running, or the host cannot reach the internet to download dependencies.

Solution

  • Verify Docker Engine and Docker Compose are installed and running:

    docker version
docker compose version

  • Confirm your host has internet access and that any proxy settings are correctly configured. See Configure Docker.

2. Containers Keep Restarting#

Issue

One or more containers enter a restart loop after make up.

Solution

Check which container is restarting and review its logs:

docker ps
docker logs -f <container_name>

Common causes:

  • Missing or incorrectly downloaded AI models. Re-run the model download steps in Build from Source.

  • Invalid .env values (for example, HOST_IP not set, or ICE server credentials not meeting length requirements).

3. No Advertisements Displayed in the Browser#

Issue

The Web UI loads but no advertisements appear.

Reason

Detections are not reaching the Web UI via MQTT, or detected labels are not mapped in ProductAssociations.csv.

Solution

  1. Confirm that PID is publishing detections to MQTT by checking PID container logs:

    docker logs -f <pid_container_name>

  2. Verify that the labels detected by PID match entries in web-ui/ProductAssociations.csv (case-insensitive match).

  3. Check AIG and ASe container logs for errors:

    docker logs -f <aig_container_name>
docker logs -f <ase_container_name>

  4. Confirm confidence and recency thresholds in .env are not set too restrictively (OBJECT_CONFIDENCE_THRESHOLD, OBJECT_RECENCY_FRAME_COUNT).

4. Slow Ad Generation on Low-Resource Systems#

Issue

Ad generation is slow on low-resource systems.

Reason

Ad generation (AIG) runs on the GPU. When Chrome also uses GPU acceleration, the two compete for GPU resources, leaving insufficient capacity for AIG and causing slow ad generation rendering instability.

Solution

  • Use Google Chrome.

  • On low-resource systems, launch Chrome with GPU acceleration disabled:

    google-chrome --process-per-site --disable-plugins --disable-gpu https://localhost:5000

  • Alternatively, in Chrome go to Settings → System and disable:

    • Continue running background apps when Google Chrome is closed

    • Use graphics acceleration when available

    Then relaunch Chrome.

  • Verify that HOST_IP, MTX_WEBRTCICESERVERS2_0_USERNAME, and MTX_WEBRTCICESERVERS2_0_PASSWORD are correctly set in .env.

5. Model Download Fails#

Issue

The YOLO11s or AIG model download step exits with an error.

Solution

  • Confirm internet access and proxy settings.

  • Ensure Python virtual environment creation succeeds (python3 -m venv).

  • For Hugging Face downloads, set the HF_HUB_ENABLE_HF_TRANSFER=1 environment variable as documented in Build from Source.

  • Ensure sufficient disk space (500 GB free recommended).

6. Video Not Rendering in Browser (MediaMTX no space left on device)#

Issue

The browser page loads, but video does not render. MediaMTX logs show no space left on device (ENOSPC).

Reason

In this scenario, ENOSPC is usually not caused by hard drive capacity. It is commonly caused by exhausting Linux host resources such as inotify watches, inotify instances, open file descriptor limits, or filesystem inodes.

Solution

  1. Confirm current inotify limits on the host:

cat /proc/sys/fs/inotify/max_user_watches
cat /proc/sys/fs/inotify/max_user_instances

  1. Increase the limits by editing sysctl configuration:

sudo nano /etc/sysctl.conf

  1. Append the following values at the end of the file:

fs.inotify.max_user_watches=1048576
fs.inotify.max_user_instances=10000

  1. Apply the updated kernel parameters immediately:

sudo sysctl -p

  1. Redeploy the Digital Signage stack and verify MediaMTX is healthy:

make up
docker logs -f mediamtx

If needed, also verify inode availability (df -i) and open file limits (ulimit -n) on the host.