DocsOperationTroubleshooting
Troubleshooting
Startup errors name the exact variable to fix. The common cases, what they mean and how to get unstuck.
First stop: the logs
$ docker compose logs -f vuzonvuzon refuses to start with an obviously unsafe config instead of coming up in a broken state, and each startup error names the variable to fix.
Common cases
| Symptom | Cause | Fix |
|---|---|---|
| Container exits right after start | DOMAIN or CF_API_TOKEN empty, or still a template value |
Fill both in .env and docker compose up -d again. |
| Startup error asks for zone/account IDs | Autodetection from DOMAIN failed, or two zones share the same name |
Add CF_ZONE_ID and CF_ACCOUNT_ID to .env. |
| “data directory not writable” | The data volume/path can’t be written | Check the vuzon-data volume mount, or VUZON_DATA_DIR if you changed it. |
| Locked out after failed logins | Login is rate-limited to 10 attempts / 15 min | Wait out the window. Behind a proxy, set TRUST_PROXY so the limit tracks real client IPs. |
| Panel answers 502 on Cloudflare actions | Upstream Cloudflare error — 401/403 are normalised to 502 on purpose | Check the token’s three scopes and its zone/account restrictions. The detailed Cloudflare error is in the server log, never in the browser. |
| Setup wizard reappeared | The vuzon-data volume was lost or replaced |
Restore it from a backup — see Backups. |
Cloudflare’s error text is logged server-side and never returned to the browser, so the log is where the real answer lives.
Still stuck?
Open an issue on GitHub. Found a security problem? Do not open a public issue — report it privately via GitHub Security Advisories.