Sync troubleshooting
Work through the message you’re seeing. Each entry is symptom → cause → fix.
“Unreachable”
Section titled ““Unreachable””Cause: the device can’t reach the sync server right now. For Home Sync this is nearly always network: you’re away from home without the VPN connected, the server host is asleep, or the container stopped.
Fix: confirm the VPN/Tailscale connection, then check the server —
curl http://<host>:4437/health should answer. Sync retries on its own;
Sync Now forces an attempt. Reconnect in the target’s ⋯ menu
is only needed if the message persists once the server is reachable.
“Offline”
Section titled ““Offline””Cause: this device has no internet (or no route to anything). Fix: none needed — sync resumes automatically when connectivity is back, and no data is lost in the meantime.
“Authentication expired — use Reconnect in the target menu”
Section titled ““Authentication expired — use Reconnect in the target menu””Cause: the target’s sign-in lapsed (long offline stretch, password change, or the device was unlinked). Fix: target’s ⋯ menu → Reconnect and sign in again. This re-authenticates without re-running setup — settings and the encryption key are untouched.
“Encryption key required to sync”
Section titled ““Encryption key required to sync””Cause: this device doesn’t hold your encryption key yet (fresh sign-in, new machine). Fix: press Unlock and enter the key. Lost it? Read Your encryption key before doing anything else.
“Pro subscription required” / “License required”
Section titled ““Pro subscription required” / “License required””Cause: the target needs an entitlement this account doesn’t have — Cloud needs Pro; Home Sync needs a license (or Pro). Fix: check Settings → Account. If you recently purchased, sign out and back in so the account refreshes.
“Vetroscope is out of date — open About → Check for updates”
Section titled ““Vetroscope is out of date — open About → Check for updates””Cause: the server (usually a Home Sync container newer than your app,
or vice versa) requires a newer client.
Fix: update the app (Settings → About → Check for Updates). If the
target row itself shows an update notice, the server is the old side —
docker compose pull && docker compose up -d on the host.
A device shows twice, or old devices linger
Section titled “A device shows twice, or old devices linger”Cause: a reinstall or migration registered the machine again. Fix: Settings → Account → Connected devices → unlink the stale entry. Its history stays in your data; only the duplicate listing goes.
Data looks different between devices
Section titled “Data looks different between devices”Give it one full sync cycle first (Sync Now on both). If a specific range is still missing or doubled, the heavy tools live in Settings → Sync:
- Force full resync — re-fetches everything from the server, ignoring the incremental cursor. Safe; takes a while on large histories.
- Wipe and re-push — erases the server’s copy and re-uploads this device’s data as the new truth. Destructive to the server copy — it asks for your encryption key for a reason. Use only when you’re sure this device has the correct history.
Home Sync server-side issues
Section titled “Home Sync server-side issues”Lost setup code, lost admin password, “database is locked”, full-disk
problems, and container upgrades are covered in the server’s own
troubleshooting guide on GitHub.
Admin password resets: docker exec vetroscope-home-sync vhs-cli reset-password --email <you> --password <new>.