FAQ

Answers to frequently asked questions.

Bare-metal - migrating from npm to pnpm #

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 --prod

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).

Docker - SSH connection refused #

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

Docker - subsystem request for sftp failed #

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.

I can’t login after installation #

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

If login fails immediately, check 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.

I don’t see status or storage updates #

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

I want to force BorgWarehouse to start on IPv6 #

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

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

Does BorgWarehouse have to be installed on the same server as BorgBackup? #

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.

What is NEXT_TELEMETRY_DISABLED? #

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

I lost the repo.json file #

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

BorgWarehouse on TrueNAS? #

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.

Contact #

borgwarehouse @ r4ven.fr