FAQ

Starting from v3.1.x, BorgWarehouse uses pnpm as its package manager. The package-lock.json is no longer included; it has been replaced by pnpm-lock.yaml.

If you are upgrading an existing bare-metal installation that was using npm, follow these steps :

1. Install pnpm : refer to the official pnpm installation guide.

2. Remove the old node_modules :

rm -rf /home/borgwarehouse/app/node_modules

3. Install dependencies with pnpm :

cd /home/borgwarehouse/app
pnpm install --frozen-lockfile

4. Rebuild the application :

pnpm run build

5. Update your systemd service : replace npm run start with pnpm run start in /etc/systemd/system/borgwarehouse.service, then reload :

systemctl daemon-reload
systemctl restart borgwarehouse.service

If BorgWarehouse fails to start with a permission error on a volume, the host directories are not owned by the user matching your PUID/PGID.

Fix it with :

chown -R YOUR_PUID:YOUR_PGID ./config ./ssh ./ssh_host ./repos

Replace YOUR_PUID and YOUR_PGID with the values set in your .env file (default: 1000).

If SSH connections are refused after starting the container, check the container logs first :

docker compose logs borgwarehouse

A common cause is an outdated sshd_config still present in your ssh_host volume from a previous installation. Remove it so the container regenerates a fresh one :

rm ./ssh_host/sshd_config
docker compose restart

This log line is harmless. Some backup clients (like Pika Backup) probe for SFTP before falling back to borg serve. If your backups complete successfully, you can ignore it.

If a borg/Vorta connection (or a manual ssh) is dropped immediately with a message like :

Connection closed by <server-ip> port <port>

or, with a more verbose client :

Received disconnect from <server-ip> port <port>:2: Too many authentication failures

…and you do not get a Permission denied (publickey), the cause is almost always client-side, not a BorgWarehouse misconfiguration.

Why it happens : BorgWarehouse only accepts public-key authentication. When your SSH client connects, it offers every identity it knows about first (all keys loaded in your ssh-agent, plus the default ~/.ssh/id_rsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519), and only then the key you passed with -i. If it offers several keys before the correct one, the SSH server can hit its per-connection authentication-attempt limit and close the connection before your repository key is ever tried.

The fix (client side) : tell your client to use only the key meant for this repository:

ssh -o IdentitiesOnly=yes -o IdentityAgent=none -p <port> \
    -i ~/.ssh/your_borgwarehouse_key borgwarehouse@<server-ip>

• IdentitiesOnly=yes : offer only the key given with -i, not the whole agent.
• IdentityAgent=none : ignore the ssh-agent for this connection.

If the connection then succeeds, borg serve will simply wait silently for the Borg protocol (an interactive ssh never gives you a shell : this is expected: the key is restricted to borg serve only).

To make it permanent, add a matching block to your ~/.ssh/config :

Host my-borgwarehouse
    HostName <server-ip>
    Port <port>
    User borgwarehouse
    IdentityFile ~/.ssh/your_borgwarehouse_key
    IdentitiesOnly yes
    IdentityAgent none

In Vorta, set the same options in the Additional SSH command line arguments / SSH key field so the correct key is used and the agent is not consulted first.

Server side (only if you host BorgWarehouse yourself) : the server allows up to MaxAuthTries 6 attempts, which is the OpenSSH default. You are free to raise this value in the server’s sshd_config and restart SSH if you need more attempts. This is optional : the client-side fix above is simpler, does not weaken the server, and is the recommended approach.

Default credentials are admin / admin. Change the password in the settings after first login.

If login fails immediately, check BETTER_AUTH_URL (or the legacy NEXTAUTH_URL) in your .env or .env.local file. The URL must exactly match the address you use in your browser, including the http:// or https:// scheme. A mismatch will silently break authentication.

Since v3.6.1, BorgWarehouse uses better-auth 1.7, which scopes account identity by (issuer, accountId) and adds a required issuer column to the account table.

On the first start after upgrading, BorgWarehouse automatically migrates your existing SQLite database (you will see Migrated account.issuer to better-auth 1.7 scoped identity in the logs). After that, you may keep seeing this warning on every start :

WARN [Better Auth]: Column "issuer" on table "account" stays nullable while the schema declares the field required, so existing rows can still hold null.

This is harmless and can be safely ignored. The migration fills the issuer value for every existing account, and BorgWarehouse always sets it when creating new accounts, so no row is ever null in practice.

The warning simply reports that the column was added as nullable. SQLite cannot add a NOT NULL constraint to an existing column without rebuilding the whole table, so BorgWarehouse intentionally leaves it nullable rather than risk your authentication database for a purely cosmetic constraint.

This follows the official procedure: better-auth’s own 1.7 upgrade guide instructs to “Add issuer as nullable during the backfill”, and lists enforcing NOT NULL only as an optional final step.

Check that your cron tasks are configured. BorgWarehouse does not run its own scheduler : you must call the API endpoints yourself.

In Docker, add HOSTNAME=:: to your .env file.

On a bare-metal install, use next start --hostname :: in package.json.

Yes. BorgWarehouse is designed to run on the server that stores the repositories and runs the BorgBackup server side. Running it on a separate machine is not supported.

Thank you to Pierrick Brun for its contribution.

Next.js can collect anonymous usage telemetry. BorgWarehouse disables it by default with this variable. If you want to contribute telemetry to the Next.js project, remove it from your .env.

Full documentation: https://nextjs.org/telemetry

Since v2.0, every change to repositories is versioned. Check the config/versions folder : you can restore a previous state from there.

It works. Follow the advice in this issue and check the closed issues for TrueNAS-specific tips.

Thank you to ToeiRei for her contributions and the help she provides to TrueNAS users.