Skip to content

Troubleshooting

cuban8IO edited this page Nov 9, 2026 · 1 revision

borg is not found

  • Check that borg --version works in a terminal (on Windows: in your WSL distribution).
  • BorgStudio looks on PATH, in the usual install locations (e.g. Homebrew) and, on Windows, in the default WSL distribution. Click Check again after installing.
  • borg older than 1.2 and borg 2 (beta) are not supported.

WSL does not start (Windows)

After wsl --install a restart is often needed. Check with wsl -l -v that a distribution (e.g. Ubuntu) is installed and runs as WSL 2.

"Host key verification failed" / the server's key changed

BorgStudio only connects to servers whose host key you confirmed. If the server was reinstalled, its key changed: check with the server's administrator, then remove the server's line from ssh/known_hosts in the data folder and connect again to confirm the new key.

The repository is locked

borg allows one writing process per repository. A backup fails with a lock error when

  • an archive of the repository is mounted – BorgStudio asks to unmount first,
  • another computer or a borg command line process is using the repository,
  • a crashed borg left a stale lock. If you are sure nothing else uses the repository, run borg break-lock <repository>.

Mounting does not work

  • Windows: see the one-time WSL setting.
  • macOS: macFUSE must be installed.
  • "No FUSE support": install borg with FUSE support (the borgbackup packages of the distributions have it).

An update failed

The old version keeps running and the status bar says why. updates/update.log in the data folder has the details. You can always download the new version from the releases page and replace the files by hand.

Where BorgStudio keeps its files

The data folder is

System Folder
Windows %LOCALAPPDATA%\BorgStudio
macOS ~/Library/Application Support/BorgStudio
Linux ~/.local/share/BorgStudio
File / folder Contents
repositories.json repositories (names and locations, never passphrases)
jobs.json backup jobs and the outcome of their last run
settings.json settings
vault.json the vault (encrypted with your PIN)
archives/ cached archive lists and file lists (encrypted with the vault's key when a PIN is set up); safe to delete
durations.json how long operations took, for the remaining-time estimates
ssh/ confirmed server host keys; temporary key files during borg calls
plugins/ external plugins
updates/ a downloaded update and update.log

Reporting a problem

Open an issue with your system, the BorgStudio version (window title), the borg version (status bar) and what happened. Never include passphrases, keys or the contents of vault.json.

Clone this wiki locally