Troubleshooting

Debug along the pipeline, upstream to downstream: camera → VPP → adapters/services → Hub → consumer. At each stage there is one question — does data come out of it? — and docker compose logs <service> answers most of them. The classes below cover the common first-deployment failures.

Nothing deploys or images won't pull

Registry authentication is the usual cause: both the Innovatrics registry (corridor images) and the GitLab registry (VPP, license manager) need a successful docker login before the first docker compose up — re-check registry access. A stack that starts but has VPP services crash-looping typically has a missing or host-mismatched iengine.lic license file.

Camera connected, no detections

Confirm VPP actually consumes the stream: the camera must be registered in VPP with a reachable RTSP URL, from inside the containers — a URL that works from your laptop can be unroutable from the Docker network. If VPP sees video but detects nothing, faces are probably too small or the frame rate dropped below usable levels in low light; re-check the numbers in Camera Selection & Placement.

Detections in VPP, no events at the Hub

Check the wiring between the layers: the camera's VPP ID must be listed on a unit in FOUNDATION_UNITS_0_CAMERAS, and the VPP adapter and broker containers must be healthy. Events for a camera not assigned to any unit go nowhere by design. The RabbitMQ biometric_events exchange is the internal seam — adapter logs on one side, Hub logs on the other localize the break.

Events flow, but clearance looks wrong

Green/red clearance depends on watchlist wiring: an allowed watchlist not registered with the Hub produces plain identification.match instead of identification.clearance.green — revisit Add People to Watchlists. Frequent condition_violation events point at obscured faces or capture conditions, and matching-quality issues belong to Tuning Identification.