Reference
Troubleshooting
Start with the failed operation in Notifications. BorgMate classifies common Borg, SSH, WSL, credential, and storage failures and keeps the technical detail with the operation.
Diagnose a failed operation
- Open Notifications from the bell in the sidebar.
- Select the failed operation and read its detail.
- Identify whether the failure is local Borg, repository access, SSH, credentials, storage, or WSL.
- Apply the relevant check below and retry once.
- If it still fails, enable Info or Debug logging, reproduce the operation, and inspect the newest log.
Common errors
| Message or symptom | What to check |
|---|---|
| Borg binary not found | Run borg --version. On Windows, run it inside WSL. Check the binary override in Settings → Advanced. |
| Borg binary not found on remote host | SSH to the host and run borg --version. Set Borg Remote Path if the binary is outside the non-interactive SSH PATH. |
| WSL is not available | Run wsl --status in PowerShell. Install a distribution and Borg inside it. |
| SSH authentication failed | Test ssh -i KEY USER@HOST, confirm the private-key path and remote authorized_keys, then retry. |
| SSH host key verification failed | Connect once from Terminal/WSL and verify the host fingerprint. Do not accept an unexpected changed fingerprint without checking the server. |
| SSH connection timed out or reset | Check network access, host, port, firewall, VPN, and whether SSH keep-alive values are suitable for the connection. |
| Wrong passphrase | Enter the repository passphrase again. Update the saved keychain entry when prompted; an SSH-key passphrase is a different credential. |
| Remote Borg executable not found | Install Borg on the SSH server or set the correct Borg Remote Path in the repository editor. |
| SMB share is unreachable | Check the server name, that the NAS is on, and that SMB file sharing is enabled on it. Try opening the share in your file manager first. |
| Server rejected SMB credentials | Re-enter the password when prompted — a wrong saved password is cleared from the keychain automatically. Confirm the account has access to the share. |
| SMB mounting requires GVFS (Linux) | Install gvfs with the SMB backend — gvfs-backends (Debian/Ubuntu) or gvfs-smb (Fedora, Arch); see the installation notes. The same error appears when the GLib/GIO libraries are missing. |
| Failed to mount SMB share inside WSL | Confirm wsl -u root -- true works (root access may be restricted by policy) and that the share opens in Windows Explorer. |
| Repository does not exist | Check the local/remote path and use Open only for a repository that Borg already initialized. |
| Repository already exists | Cancel Create and use Open to add the existing repository. |
| Invalid or incompatible repository | Confirm the path and select the same Borg major version that created it. |
| Repository is locked | Wait for other Borg operations to finish. Break a lock only after confirming that no Borg process uses the repository. |
| No space left on device | Check free space on both source and repository filesystems. Free space, then retry; prune followed by compact may reclaim repository space. |
| Operation completed with warnings | Read the detail for changed, unreadable, missing, or unmatched source files and decide whether the archive is acceptable. |
| Unknown error or exit code | Enable logging, reproduce once, and inspect the newest log together with the Notification detail. |
Handle a stale repository lock
BorgMate automatically retries some transient SSH and stale-lock failures. If a lock remains:
- Confirm that BorgMate, another computer, and scheduled jobs are not using the repository.
- Close any abandoned Borg process and retry.
- As a last resort, run the matching Borg version's
break-lockcommand against the repository.
Never break an active lock.
Removing a lock while another Borg process writes to the repository can damage repository state.
A scheduled backup did not run
- Confirm the repository is Scheduled and shows a plausible next run.
- Confirm BorgMate was running in the tray, or wake scheduling was enabled and supported.
- Check Notifications for a Deferred result caused by battery power.
- Check the journal for a failed run: scheduled backups never show a password prompt, so a repository passphrase, SSH key passphrase, or SMB password that is not saved in the keychain fails the run with a notification. Run a backup manually once and save the credential.
- Enable Run missed backups on startup if the computer can be off at the scheduled time.
- On macOS, save Settings once with wake enabled to grant administrator permission.
- On Linux, confirm systemd 254+ and a compatible desktop user session.
- On Windows, confirm Task Scheduler is available and Borg still runs inside WSL.
Collect useful diagnostics
- Open Settings → Advanced → Logging.
- Enable logging and select Info first; use Debug when Info is insufficient.
- Reproduce the problem once.
- Open the application-data
BorgMate/logsfolder described in the settings reference. - Review the newest file and include the relevant operation detail when requesting help.
Review diagnostics before sharing them.
Remove personal paths, host names, user names, repository URLs, and other identifying data. Never share passphrases, private SSH keys, keychain contents, or secret tokens.
Still stuck? Contact contact@oddbit.io with the BorgMate version, operating system, Borg version, operation type, exact error detail, and sanitized log excerpt.