Sync Not Working

ZestSSH supports two sync methods: Cloud Sync (Firebase-based) and WebDAV backup destinations. This page covers common issues with both.

Cloud Sync Issues

Wrong Passphrase

Symptom: Sync fails with “Wrong passphrase” or “Decryption failed”.

Cause: Cloud Sync uses end-to-end encryption with a passphrase you set when enabling sync. The passphrase derives an encryption key via Argon2id, and all data is encrypted with AES-256-GCM before leaving your device. If you enter the wrong passphrase, decryption fails.

Solutions:

1. Re-enter the correct passphrase. The passphrase is case-sensitive and whitespace-sensitive.
2. If you forgot the passphrase, you will need to reset sync. This deletes the encrypted data from the cloud and re-uploads with a new passphrase. Your local data is not affected.
3. Check for keyboard layout issues. Special characters may differ between devices if your keyboards use different layouts.

Sign-In Issues

Symptom: Cannot sign in with Google or Apple.

Solutions:

1. Check your internet connection. Firebase Auth requires an active connection.
2. Google Sign-In on Android: Ensure Google Play Services is up to date.
3. Apple Sign-In on iOS: Ensure you are signed into your Apple ID in iOS Settings.
4. Desktop platforms: ZestSSH uses a local OAuth callback server (zestssh://auth/callback). If another app is intercepting this URL scheme, authentication may fail.

Sync Conflict

Symptom: Changes on one device do not appear on another, or data reverts to an older version.

Cause: ZestSSH uses an additive merge strategy for sync. When two devices modify the same record, the last upload wins for that record. This can cause unexpected behavior if you edit the same connection on two devices simultaneously.

Solutions:

1. Sync before editing. Pull the latest data before making changes.
2. Avoid simultaneous edits. If you need to edit connections on multiple devices, do them one at a time and sync between edits.
3. Force re-upload. If data is inconsistent, you can trigger a full re-upload from the device with the correct data by changing the sync passphrase. This re-encrypts and re-uploads everything.

Sync Not Triggering

Symptom: Changes are not automatically synced.

Solutions:

1. Check that auto-sync is enabled in Settings > Cloud Sync.
2. Manual sync: Pull down on the home screen or use the sync button in profile settings.
3. Check that you are signed in. Open Profile to verify your account is connected.

WebDAV Issues

Authentication Failed

Symptom: WebDAV backup fails with 401 or 403 errors.

Solutions:

1. Verify credentials. Check the username and password for your WebDAV server.
2. URL format. Ensure the WebDAV URL is correct and includes the full path to the target directory (e.g. https://cloud.example.com/remote.php/dav/files/user/ZestSSH/).
3. HTTPS required. ZestSSH only connects to WebDAV servers over HTTPS for security.

Connection Timeout

Symptom: WebDAV operations time out.

Solutions:

1. Check server availability. Access the WebDAV URL in a browser to verify the server is responding.
2. Firewall rules. Ensure outbound HTTPS is not blocked on your network.
3. Self-signed certificates. ZestSSH may reject self-signed SSL certificates. Use a certificate from a trusted CA (Let’s Encrypt is free).

File Size Limits

Symptom: Large backups fail to upload.

Solutions:

1. Check your WebDAV server’s upload size limit (e.g. Nextcloud defaults to 512 MB, but PHP or nginx may impose lower limits).
2. ZestSSH backup files are typically under 1 MB unless you have thousands of connections. If your backup is unusually large, check for corruption.

Local Backup Issues

Import Fails with “Invalid backup file format”

Cause: The file does not start with the “ZEST” magic bytes. It may be corrupted, renamed from another format, or truncated during transfer.

Solutions:

1. Verify the file has the .zest extension and was exported from ZestSSH.
2. Re-export the backup from the source device.
3. If transferring between devices, use a method that does not modify the file (AirDrop, direct USB copy, cloud storage). Email attachments may be corrupted by encoding.

”Wrong password or corrupted backup”

Cause: The password does not match, or the encrypted data has been corrupted.

Solutions:

1. Re-enter the backup password carefully. It is case-sensitive.
2. If you are certain of the password, the file may be corrupted. Try the original copy if you have one.
3. The backup password is separate from the Cloud Sync passphrase. They can be different.

Legacy Unencrypted Backup Warning

Symptom: After importing, ZestSSH shows a warning about an unencrypted legacy backup.

Cause: The backup was created by an older version of ZestSSH that did not encrypt backups. Current versions always encrypt.

Action: The import succeeded, but you should immediately export a new encrypted backup with a strong password (minimum 12 characters) and delete the old unencrypted file.