Troubleshooting

Use this guide to resolve the most common issues encountered when deploying and running the Video Intelligence Framework (VIF). If an issue persists after working through the relevant section, gather the diagnostics listed at the end of this article before contacting Wowza Support.

Service and startup

Problem	Resolution
Service won't start	Check the logs: docker compose --profile all logs -f
GPU not detected	Verify nvidia-container-toolkit is installed and that nvidia-smi returns valid output on the host. VIF requires NVIDIA Turing architecture or newer (T4, L4, RTX 20xx+), CUDA 12.8+, and driver 570+.
First start takes a long time	Expected. On first start, VIS downloads model weights and compiles TensorRT engines for your specific GPU. This can take 20+ minutes and is a one-time process — compiled engines are cached in ./vis/models/ for future starts.
Connection refused after restart	VIS takes roughly 1–3 minutes to initialize after a restart. Wowza Streaming Engine reconnects automatically — no action needed.
Model download fails on first start	See the air-gapped deployment section in VIS_DEPLOYMENT.md for pre-downloading model weights.
VIS health check	Confirm VIS is ready by running curl -s http://localhost:5001/health.

Connectivity and licensing

Problem	Resolution
Engine cannot connect to VIS	Check network connectivity, confirm port 5001 is open, and verify VIS_HOST is set correctly in .env.
VIS_HOST resolves to the wrong container (all-in-one Docker)	When running with --profile all, set VIS_HOST=video-intelligence-service.docker. Using localhost resolves to the WSE container, not VIS, and the connection will fail.
Authentication errors between WSE and VIS	Confirm VIS_API_KEY is identical in both the WSE and VIS .env files.
License rejected on connection	Confirm your VIS_LICENSE matches the WSE engine license key it was issued for. The keys are paired; a VIS license issued for one engine key will be rejected by another.
Cannot log in to Manager	Confirm WSE_ADMIN_USER and WSE_ADMIN_PASSWORD in .env are correct and that WSE started successfully.

Detection issues

Problem	Resolution
Object detection is not triggering	Verify the stream name matches the configured stream_name regex pattern. By default, streams matching object.* trigger object detection (e.g., object or objectDetect).
Scene analysis is not triggering	Verify the stream name matches the scene.* pattern (or your configured override) and that detector_type is set to scene in your VIF configuration.
Stream connects, but no detections appear	Open the VIF Dashboard in WSE Manager and confirm the stream appears with a green status. Check that the active toggle is on and that the detection rate is above 0%.
Too many false positives	Raise the confidence_threshold setting (default 0.3) in your VIF configuration.
No detections on a known-good stream	Lower the confidence_threshold for testing, then tune upward. Also, confirm the stream's class_names list includes the objects you expect to detect.
Stale results after changing the model or GPU	Stop VIS, delete the contents of ./vis/models/engines/, and restart. VIS will recompile TensorRT engines for the new configuration.

Output channels

Problem	Resolution
No overlay visible in the player	The overlay output stream has -vi appended to the stream name (for example, object_mystream1-vi). Point your player to that URL.
Webhook endpoint not receiving payloads	Test the webhook URL independently to confirm it is reachable. Verify the auth headers in Webhooks.json and that the listener's methods field is not set to ["disabled"].
ID3 tags not appearing in HLS player	Confirm the Id3Event listener is enabled and that methods is set to immediate, batch, or rollup (not disabled).
Detection logs missing	VIF detection logs are written to wowzastreamingengine_vi.log under ./wse/logs/ and only when the LogFiles listener is enabled.
Listener appears active but filters out detections	Each event listener has its own confidence_threshold, separate from the detection threshold. Lower the listener-level threshold if needed.

Performance and capacity

Problem	Resolution
GPU utilization is high, and frames are dropping	The baseline capacity is roughly 8 concurrent 720p streams at 10 FPS on a single NVIDIA T4 using the medium model. If you are at or above this, reduce the stream count, drop to a smaller model variant (nano or small), or add GPU capacity.
GPU utilization is low, and analysis is slow	Increase concurrent_executions to run more parallel model instances. Defaults are 10 for object and 1 for scene.
GPU is not used at all by the container	Confirm nvidia-container-toolkit is installed and that the Docker Compose service has deploy.resources.reservations.devices configured. Verify with: docker run --gpus all nvidia/cuda:12.8-base nvidia-smi.
High latency on Split-Server deployments	Increase frame_buffer to compensate for network latency between WSE and a remote VIS host.

Limitations

The following are documented limitations rather than defects. Plan deployments accordingly.

• Scene analysis is experimental. Accuracy varies by scene complexity, and output quality may change between releases. The sensitivity, holdback, and duration parameters require tuning for each environment.
• Scene analysis requires the internet on first run. OpenAI CLIP base weights are downloaded the first time scene analysis runs. Air-gapped deployments must pre-download these weights. This requirement will be removed in a future release.
• No cross-camera tracking. Object tracking is per-stream, and identity is not preserved across cameras.
• Object detection is limited to 80 COCO classes when using built-in models. Custom RF-DETR training is the supported path for additional object classes.
• No chained or post-processing models. Running a second model on bounding-box crops (for example, license-plate reading after vehicle detection) is not supported.

Information to gather before contacting Support

If you need to escalate an issue, please collect the following before opening a case. Having these in hand significantly reduces resolution time.

• WSE logs: wowzastreamingengine_access.log and wowzastreamingengine_error.log from ./wse/logs/ (or /usr/local/WowzaStreamingEngine/logs).
• VIF detection log: wowzastreamingengine_vi.log from ./wse/logs/, if the LogFiles listener is enabled.
• VIS container logs: Output of docker compose --profile vi-service logs.
• Configuration files: .env (redact VIS_LICENSE and VIS_API_KEY before sharing), docker-compose.yaml, and video-intelligence.json from ./wse/conf/.
• Environment details: OS and version, Docker version, Docker Compose version, GPU model, NVIDIA driver version, CUDA version, and full nvidia-smi output.
• Stream details: Ingest protocol (RTMP/RTSP/SRT/WebRTC), stream name and regex pattern in use, resolution, frame rate, and the number of concurrent streams.
• Deployment topology: Docker profile in use (all, wse, or vi-service) and whether the deployment is all-in-one, split-server, air-gapped, on-prem, cloud, or hybrid.
• Reproduction steps: A numbered description of what was done when the issue occurred.
• Health check output: curl -s http://localhost:5001/health.
• Optional: Screenshots of the VIF Dashboard and per-stream detail views from WSE Manager.