# Common Issues When Running the Multi-Camera Face Tracker

> Learn to troubleshoot common multi-camera face tracker issues like missing YAML configs, missing InsightFace models, invalid camera indices, and permission errors to ensure smooth operation.

- Repository: [AarambhDevHub/multi-cam-face-tracker](https://github.com/aarambhdevhub/multi-cam-face-tracker)
- Tags: troubleshooting
- Published: 2026-02-23

---

**Most runtime failures in the multi-camera face tracker stem from missing YAML configurations, absent InsightFace model weights in `./models/buffalo_l`, invalid camera indices, or permission errors when writing to `data/screenshots` and `logs/` directories.**

The `aarambhdevhub/multi-cam-face-tracker` repository combines PyQt5, InsightFace, and multi-threaded camera management into a desktop security application. When running the multi-camera face tracker, operators frequently encounter resource misconfigurations, hardware constraints, and threading bottlenecks that manifest as specific error messages in `logs/app.log`. Understanding the exact file paths and function names where these errors are raised allows you to diagnose root causes without reading the entire codebase.

## Configuration Loading Errors

In [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py), the `load_config` function (lines 29-55) attempts to read [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml). If the file is missing or malformed, the parser raises an exception that the function catches, logging `Failed to load config` before the application aborts. Ensure the YAML contains the required top-level keys `app` and `recognition`, and that the process has read permissions for the file.

```python
from main import load_config

try:
    cfg = load_config('config/config.yaml')
except Exception:
    # The logger already printed a detailed message

    raise SystemExit("Unable to start – fix config.yaml")

```

## Model Initialization and Device Mismatches

The `FaceDetector` class in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) implements `_load_model` (lines 41-55) to wrap the InsightFace `FaceAnalysis` constructor. This method logs `Failed to load face detection model` when the `./models/buffalo_l` directory is missing or when the configured `device` (either `"cpu"` or `"cuda"`) is unsupported by your OpenCV build. On CPU-only systems, ensure `device: "cpu"` is set explicitly to prevent CUDA initialization errors.

```python
import os
from core.face_detection import FaceDetector

model_dir = "./models/buffalo_l"
if not os.path.isdir(model_dir):
    raise RuntimeError(f"Model directory missing: {model_dir}")

detector = FaceDetector(cfg)   # will now succeed

```

## Known Faces Directory Issues

During startup, `load_known_faces` in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) (lines 66-70) scans the `known_faces_dir` (default `data/known_faces`). If the directory does not exist, the function logs a warning and skips loading, causing all detections to appear as "Unknown". Populate this folder with `.jpg`, `.jpeg`, or `.png` files named after the person to enable recognition.

## Camera Source Connection Failures

Each camera runs in a daemon thread managed by `CameraManager` in [`core/camera_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/camera_manager.py). The `_capture_frames` method checks `cap.isOpened()` and logs `Failed to open camera ID …` at line 145 when the index or RTSP string in [`config/cameras.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/cameras.yaml) is invalid, the device is offline, or the process lacks permission to access the hardware. Verify the source string matches your system's available video devices.

```python
from core.camera_manager import CameraManager

cm = CameraManager('config/cameras.yaml')

# Try to start a specific camera, fall back if it fails

if not cm.start_camera(0):
    print("Camera 0 could not be opened – checking other sources")
    for cam_id in cm.cameras:
        if cm.start_camera(cam_id):
            break

```

## Frame Queue Overflow and Performance Bottlenecks

When a producer thread captures frames faster than the consumer processes them, the fixed-size queue fills up. In [`core/camera_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/camera_manager.py) lines 71-77, the capture thread drops the oldest frame when the queue is full to prevent UI blocking. If you observe stutter, reduce the `fps` setting in your camera configuration or increase the `maxsize` parameter of the queue.

## Screenshot Saving Permission Errors

The `AlertSystem` class in [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) implements `_capture_screenshot` (lines 23-30) to write images via `cv2.imwrite`. When the `screenshot_dir` (default `data/screenshots`) is missing or the process lacks write permissions, the method logs `Failed to save screenshot to …`. Ensure the directory exists and is writable by the user running the application.

```python
from core.alert_system import AlertSystem
import numpy as np
import cv2
import time

alert = AlertSystem(cfg)
dummy_frame = np.zeros((480, 640, 3), dtype=np.uint8)
path = alert._capture_screenshot(dummy_frame, camera_id=1,
                                face_name="test", timestamp=time.time())
print("Saved to:", path)

```

## Alert Sound Playback Failures

Audio alerts rely on `pygame` mixer initialization in `_play_alert_sound` ([`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) lines 5-12). If `assets/alert.wav` is missing or corrupted, or the system audio device is unavailable, the function catches the exception and logs `Error playing alert sound`. Verify the file path in [`config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config.yaml) points to a valid WAV file and that your audio subsystem is active.

## Telegram Integration and Network Timeouts

The `TelegramManager` in [`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py) (line 58) catches `TelegramError` when the bot token or chat ID is invalid, or when network timeouts prevent reaching the Telegram API. The error is logged as a failure to send the alert. Confirm your [`config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config.yaml) contains the correct credentials and that the host has outbound internet access.

## UI Crashes and Threading Exceptions

The PyQt5 event loop in [`ui/main_window.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/main_window.py) wraps critical callbacks in `try/except` blocks (lines 335-337) to catch unhandled exceptions such as `None` frames from a failed camera or missing image resources. These errors are forwarded to `logger.error` and recorded in `logs/error.log`. Check this log file for stack traces when the interface freezes or closes unexpectedly.

You can disable optional features that trigger these errors by modifying the configuration dictionary before initializing components:

```python
cfg['telegram']['enabled'] = False          # skip Telegram

cfg['app']['alert_sound'] = ''              # no sound

alert = AlertSystem(cfg)                    # safe startup

```

## Summary

- **Verify [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml)** exists and contains valid YAML with required `app` and `recognition` keys before starting the application.
- **Ensure `./models/buffalo_l`** contains InsightFace weights and that the `device` setting matches your hardware capabilities (`cpu` vs `cuda`).
- **Create `data/known_faces`** and populate it with labeled images to avoid "Unknown" detections and warnings during face loading.
- **Check camera indices** in [`config/cameras.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/cameras.yaml) against available system devices to prevent `Failed to open camera ID` errors.
- **Confirm write permissions** for `data/screenshots` and `logs/` directories so the alert system and logger can persist files.
- **Disable optional features** (Telegram, sound) in [`config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config.yaml) if they cause startup failures or require unavailable resources.

## Frequently Asked Questions

### Why does the application crash immediately on startup?

Immediate crashes typically occur when [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py) cannot find [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) or the file contains malformed YAML that triggers an exception in `load_config` (lines 29-55). Verify the file exists in the `config/` directory and contains the required `app` and `recognition` keys, and ensure the process has read permissions.

### How do I resolve "Failed to open camera ID" errors?

This error originates in [`core/camera_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/camera_manager.py) at line 145 when `cv2.VideoCapture` cannot access the specified index or RTSP stream defined in [`config/cameras.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/cameras.yaml). Check that the camera is physically connected, the index matches your system (often `0` for built-in, `1` for USB), and the user running the tracker has permission to access video devices.

### Why are screenshots not being saved when a face is detected?

The `_capture_screenshot` method in [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) (lines 23-30) logs a failure when `cv2.imwrite` returns `False`, usually because the `data/screenshots` directory does not exist or lacks write permissions. Create the directory manually and ensure the running user has write access, or specify an alternative path in [`config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config.yaml).

### Can I run the tracker without Telegram alerts or sound notifications?

Yes. Set `telegram.enabled: false` and `app.alert_sound: ""` (empty string) in [`config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config.yaml). The `AlertSystem` and `TelegramManager` classes gracefully skip initialization when these features are disabled, preventing related errors from appearing in the logs and allowing the tracker to run on headless or muted systems.