Skip to main content

Troubleshooting

Fixes for common problems, collected in one place. Each section names the symptom; follow the steps in order.

Worker and cluster​

Live stream from the worker doesn't show​

The worker connects out to the master for enrollment and inference, but the live stream is the one case where the master connects back to the worker on port 8765. If enrollment works but the stream stays blank, that inbound connection is being blocked, most often by a firewall on the worker machine.

Windows: the Windows Defender Firewall blocks incoming connections to port 8765 by default. Open PowerShell as Administrator and add an inbound rule:

New-NetFirewallRule -DisplayName "Superhome Worker 8765" -Direction Inbound -Protocol TCP -LocalPort 8765 -Action Allow -Profile Private,Domain

Also make sure your network is set to Private (not Public) in Windows, otherwise the rule won't apply.

Any OS: confirm the master can reach the worker. From a terminal on the same network, run curl -m 5 http://<WORKER_IP>:8765/api/status. If it times out, the port is blocked (firewall) or unreachable on the network.

If the firewall is open and the stream still doesn't show, reboot the worker machine: a full reboot is recommended so the new rules and the container networking take effect. If it still doesn't work after the reboot, do a clean restart of master-worker mode.

RTSP camera stream issues​

If detections never trigger, the worker may not be receiving the camera feed. The camera URL is configured on the master (rtsp_url). Test that the stream itself is valid by opening the same RTSP URL in VLC (Media → Open Network Stream → paste the rtsp://… URL). If VLC can't play it, the problem is the camera/URL, not Superhome.

Clean restart of master-worker mode​

If the cluster gets into a bad state (worker stuck, won't reconnect, stream broken after config changes), do a clean re-enrollment:

  1. On the worker, from the folder that holds docker-compose.yml, tear it down including its data volume: 
    docker compose down -v
  2. On the master, open the Superhome Hub → Cluster and revoke the worker.
  3. Re-add the worker from scratch by following the steps in Add a Worker (generate a fresh enrollment key, launch, approve).