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.

Client and server protocol mismatch

Vsync refuses incompatible peers instead of guessing. Update the client or server named in the error. For a team-wide protocol change, coordinate both sides as described under Upgrade.

Open the admin dashboard to inspect deduplicated store size and free space. Run a GC dry run, review the retention configuration, 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.

Vsync Documentation