Troubleshooting
Toposync is in Alpha Early Access. That means troubleshooting is part of the product work right now: there are many operating systems, cameras, protocols, Home Assistant setups, Docker hosts, GPUs, browsers, networks, and installation paths to validate.
This page is the starting point. More focused troubleshooting docs will be added over time.
First checks
Start with the basics:
- Confirm which installation path you are using: Python, Docker, Home Assistant OS add-on, or processing server.
- Confirm the Toposync process is running.
- Open the health endpoint when available, usually
/api/health. - Check the browser console or server logs.
- Confirm the active data directory and file locations.
- Restart after changing environment variables or command-line flags.
If the issue involves cameras, note the protocol and camera model. If it involves Home Assistant OS, note the add-on version, host architecture, and whether the problem happens through ingress, direct port, or both.
Find the focused guide
| Area | Use this guide |
|---|---|
| Choosing the right install path | Choose your installation |
| Python on Linux/macOS | Python on Linux and macOS |
| Python on Windows | Python on Windows |
| Docker CPU | Docker CPU |
| Docker CUDA | Docker CUDA |
| Home Assistant OS add-on install | Home Assistant OS add-on |
| Home Assistant OS operation | Home Assistant add-on troubleshooting |
| Processing server on Linux/macOS | Processing server on Linux and macOS |
| Processing server on Windows | Windows processing service |
| Processing server with Docker | Processing server with Docker |
| Live viewing and streaming | Camera live viewing |
| Ports and connection refused | Ports |
| Environment variables | Environment variables |
| Data directory and disk usage | File locations |
| Broken settings or config recovery | Configuration |
Common symptoms
| Symptom | First place to check |
|---|---|
| Browser cannot open Toposync | Process logs, port binding, Ports. |
connection refused | Wrong host, wrong port, service stopped, container port not published, or Home Assistant add-on direct port not enabled. |
| UI loads but cameras do not | Camera URL, RTSP/ONVIF credentials, stream source, Camera live viewing. |
| Home Assistant sidebar works but direct URL does not | Add-on network settings, ingress versus direct-port mode, Home Assistant add-on troubleshooting. |
| Pipelines do not produce events | Pipeline enabled state, operator diagnostics, camera mapping, processing server assignment. |
| Processing server is unreachable | Basic auth, host URL, firewall, service status, and the relevant processing server install guide. |
| Disk usage grows | Data directory, generated files, pipeline snapshots, streaming runtime files, File locations. |
Open a GitHub issue
For ordinary bugs, use GitHub Issues.
Good issues help the project validate the real world faster. Include:
- Toposync version;
- installation path;
- operating system and architecture;
- browser or app surface;
- Home Assistant OS/add-on version when relevant;
- camera model and protocol when relevant;
- Docker, GPU, DirectML, CUDA, or processing server details when relevant;
- expected behavior;
- actual behavior;
- sanitized logs and screenshots;
- exact steps to reproduce.
Do not include passwords, tokens, private URLs, camera credentials, private camera images, personal data, or vulnerability details in a public issue.
Contribute fixes or docs
Contributions are welcome. Start with CONTRIBUTING.md for setup, development workflow, tests, documentation rules, and pull request expectations.
Small focused contributions are especially useful during Alpha Early Access:
- improving installation docs;
- adding troubleshooting notes from real devices;
- reporting camera compatibility details;
- fixing broken links or unclear steps;
- adding focused tests around distribution or Home Assistant behavior.
Security issues
Do not report vulnerabilities in public issues.
Use private GitHub vulnerability reporting or a private GitHub Security Advisory when available. See SECURITY.md.