Client troubleshooting

The installer or app will not open

The preview packages are not yet signed. Follow the Windows or macOS warning steps under Install Vsync. Only bypass the expected unrecognized app or developer cannot be verified warning for a package from the official Vsync downloads page.

Do not bypass a malware, damaged-file, or invalid-package warning. Download the package again and report the exact message, operating system, and Vsync version.

The desktop app cannot reach the server

Enter the server URL without /admin, then use the lightning button beside it to check the connection. You can also open https://<server>/healthz in a browser; it should show ok without a certificate warning.

If the health check fails, the server administrator must check DNS, HTTPS, and the Vsync service.

“No server” or “run vsync login”

Sign in again and confirm the server address:

vsync login --server https://builds.example.com

For CI, verify that both VSYNC_SERVER and VSYNC_TOKEN are present.

Unauthorized or invalid token

For a password account, confirm that you opened the invite link and use the same name shown there. Ask an administrator for a new invite if needed.

For a raw token, it may be mistyped or revoked. Ask an administrator to issue a new one.

No build root configured

Set one. For a one-off command without a build root, pass both an explicit store and output directory:

vsync root D:\builds
vsync --store D:\vsync-cache fetch <build-id> --out D:\temporary-build

Build or stream not found

Check the selected game and platform. Streams are scoped to a game, and versions are unique within a game and platform. Fetching a stream needs a platform too: it resolves to the newest build of that platform in the stream, so a stream with no build for it fails.

Interrupted download

Run the fetch again. Completed chunks remain in the cache and are reused. The old checkout remains intact until staging completes.

A checkout looks damaged

Fetch the same build again from the desktop app, or run vsync fetch against the managed destination. Vsync reconstructs the checkout from verified chunks.

Disk usage is too high

Inspect Settings in the desktop app or run vsync cache status. Delete unused checkouts separately from pruning or clearing the cache.