Recovering from a Failed Borg Backup Repository: Lessons from a Homelab Mishap

Introduction to Borg Backup

I’ve been using Borg Backup for years, and it’s been a reliable tool in my homelab setup. However, like any complex system, it’s not perfect, and I recently had to deal with a failed repository. This experience taught me a lot about the recovery process, and I’d like to share my findings with you.

Understanding Borg Backup Repositories

Before we dive into recovery, it’s crucial to understand how Borg Backup repositories work. A repository is essentially a storage location for your backups, and it can be hosted locally or remotely. Borg uses archives to store individual backups within the repository, and each archive contains a snapshot of your data at a particular point in time. I’ve seen this go wrong when the repository becomes inconsistent, so it’s essential to understand the basics.

Identifying the Issue

My repository failed due to a disk error, which caused it to become inconsistent. The first sign of trouble was an error message indicating that the repository was locked. Attempting to unlock it manually didn’t work, and I was left with a unusable repository. This is where people usually get burned, so it’s essential to know how to identify and fix these issues.

Recovery Steps

To recover from a failed Borg Backup repository, you’ll need to follow these steps:

Stop any ongoing Borg processes: Make sure no Borg processes are running in the background. You can check this by running pgrep borg or ps aux | grep borg. Don’t bother with pkill unless you’re sure it won’t cause more harm.
Check the repository integrity: Run borg check --repair /path/to/repo to verify the repository’s integrity and attempt to repair any damage. The real trick is to run this command as soon as you notice any issues.
Recreate the repository: If the repair process fails, you may need to recreate the repository from scratch. This involves deleting the existing repository and creating a new one using borg init /path/to/new/repo.
Restore from a previous archive: If you have a previous archive that’s intact, you can restore from it using borg restore /path/to/repo::archive_name /path/to/restore/location. In practice, this is usually the most straightforward step.

Example: Recovering from a Failed Repository

Let’s say my failed repository is located at /mnt/backup/borg-repo, and I want to recover from it. I’d start by stopping any ongoing Borg processes:

pgrep borg | xargs kill

Next, I’d attempt to repair the repository:

borg check --repair /mnt/backup/borg-repo

If the repair process fails, I’d recreate the repository:

borg init /mnt/backup/new-borg-repo

Finally, I’d restore from a previous archive:

borg restore /mnt/backup/new-borg-repo::2026-07-01 /mnt/restore/location

Security Considerations

While recovering from a failed Borg Backup repository, it’s essential to keep security in mind. Make sure to use secure protocols when transferring data between repositories, and consider using encryption to protect your backups. You can use tools like GnuPG to encrypt your backups. I usually start with a simple setup and then add more security features as needed.

Lessons Learned

Recovering from a failed Borg Backup repository can be a challenging process, but with the right steps and precautions, you can get your backups up and running again. It’s essential to regularly check the integrity of your repositories and have a plan in place for disaster recovery. For more information on Borg Backup, you can visit the official Borg website.