Server troubleshooting

Service does not start

sudo systemctl status vsync-server
sudo journalctl -u vsync-server -n 100 --no-pager

Common causes are an invalid TOML setting, a root directory the vsync user cannot write, or another process already listening on the configured address.

Public health check fails

Check each layer separately:

curl http://127.0.0.1:7770/healthz
sudo systemctl status caddy
curl https://builds.example.com/healthz

If the local request works but HTTPS fails, inspect DNS, firewall rules, the Caddy configuration, and Caddy logs.

Uploads fail with request too large

Ensure the reverse proxy accepts bodies up to 256 MB. The Caddy example uses:

request_body {
    max_size 256MB
}

Clients receive 401

• Confirm the token is active with vsync-server token list.
• Check that the client uses the correct server URL.
• For Perforce, confirm the exact P4PORT, server trust, p4 binary, and a client ticket created with p4 login -a.

Disk is filling up

Open the admin dashboard to inspect deduplicated store size and free space. Run a GC dry run, review retention values, and only then run the sweep. Check for large backups or unrelated files on the same volume as well.

Database permission errors

The packaged service runs as vsync. The data root and its contents must be writable by that user. Run server maintenance commands with sudo -u vsync to avoid creating root-owned files in the data directory.