Troubleshooting Guide

This guide covers common issues, error messages, and solutions when using Borgitory.

Quick Diagnostics

System Health Check

Before troubleshooting specific issues, verify your system meets the basic requirements:

Check BorgBackup Installation:

# Verify Borg is installed and accessible
borg --version

# Check PATH includes Borg location
which borg

# Test basic Borg functionality
borg help

Check Rclone Installation (for cloud sync):

# Verify Rclone is installed
rclone --version

# List configured remotes
rclone listremotes

# Test basic functionality
rclone help

Check System Resources:

# Check disk space
df -h

# Check memory usage
free -h

# Check CPU usage
top

Docker-Specific Checks:

# Check container status
docker ps

# Check container logs
docker logs borgitory

# Check FUSE availability
ls -la /dev/fuse

Installation Issues

PyPI Installation Problems

Python Version Compatibility

Error: borgitory requires Python 3.11 or higher

Solution:

# Check Python version
python --version

# Install Python 3.11+ using pyenv (recommended)
curl https://pyenv.run | bash
pyenv install 3.11.0
pyenv global 3.11.0

# Or use system package manager
# Ubuntu/Debian:
sudo apt update
sudo apt install python3.11 python3.11-pip

# Create virtual environment with correct Python
python3.11 -m venv .venv
source .venv/bin/activate
pip install borgitory

Missing System Dependencies

Error: Failed building wheel for pyfuse3

Solution:

# Ubuntu/Debian
sudo apt update
sudo apt install python3-dev libfuse3-dev pkg-config

# CentOS/RHEL/Fedora
sudo dnf install python3-devel fuse3-devel pkgconfig

# macOS
brew install macfuse pkg-config

Permission Errors During Installation

Error: Permission denied when installing borgitory

Solution:

# Use virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate
pip install borgitory

# Or install for user only
pip install --user borgitory

Docker Installation Problems

FUSE Mount Failures

Error: Archive browsing disabled - FUSE not available

Solution:

# Ensure container runs with proper capabilities
docker run -d \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  mlapaglia/borgitory:latest

# Check if FUSE is available on host
ls -la /dev/fuse

# Install FUSE if missing
# Ubuntu/Debian:
sudo apt install fuse3

# Load FUSE kernel module if needed
sudo modprobe fuse

Volume Mount Issues

Error: No such file or directory when accessing backup sources

Solution:

# Verify source paths exist on host
ls -la /path/to/backup/sources

# Check volume mounts in Docker Compose
volumes:
  - /actual/host/path:/mnt/container/path:ro

# Ensure paths are under /mnt/ in container
- /home/user/documents:/mnt/backup/documents:ro

Repository Issues

Repository Connection Failures

Invalid Repository Path

Error: Repository not found or inaccessible

Diagnosis:

# Test repository access directly with Borg
borg info /path/to/repository

# Check if path exists and is accessible
ls -la /path/to/repository

# Verify permissions
stat /path/to/repository

Solutions:

  • Verify the repository path is correct

  • Ensure the path is accessible from within the container (use /mnt/ prefix for Docker)

  • Check file permissions allow read/write access

  • For remote repositories, verify SSH keys and network connectivity

Incorrect Passphrase

Error: Invalid passphrase or corrupted repository

Diagnosis:

# Test passphrase directly with Borg
borg list /path/to/repository
# Enter passphrase when prompted

Solutions:

  • Verify the passphrase is exactly correct (case-sensitive)

  • Check for hidden characters or encoding issues

  • Try accessing the repository with Borg CLI to confirm passphrase

  • If passphrase is lost, repository cannot be recovered

Repository Corruption

Error: Repository integrity check failed

Diagnosis:

# Check repository integrity
borg check /path/to/repository

# Detailed check with repair option
borg check --repair /path/to/repository

Solutions:

  • Run borg check --repair to attempt automatic repair

  • If repair fails, restore from backup repository

  • Check underlying storage for hardware issues

  • Consider filesystem corruption on storage device

Backup Operation Failures

Backup Job Failures

Insufficient Disk Space

Error: No space left on device

Diagnosis:

# Check available space
df -h

# Check repository location specifically
df -h /path/to/repository

Solutions:

  • Free up disk space on repository storage

  • Move repository to location with more space

  • Implement pruning policies to remove old archives

  • Consider using compression to reduce space usage

Permission Denied Errors

Error: Permission denied accessing source files

Diagnosis:

# Check source path permissions
ls -la /path/to/source

# Test read access
cat /path/to/source/testfile

Solutions:

  • Ensure Borgitory has read access to source directories

  • For Docker, check volume mount permissions

  • Run container with appropriate user ID

  • Use sudo if necessary for system directories

Exclude Pattern Issues

Warning: Exclude pattern not matching any files

Diagnosis:

  • Review exclude patterns for syntax errors

  • Test patterns with find command

  • Check if patterns are relative to source path

Solutions:

# Test exclude patterns
find /path/to/source -name "*.tmp"

# Common exclude patterns
*.tmp
*.log
.git/
__pycache__/
node_modules/

Cloud Sync Issues

Connection Failures

Invalid Credentials

Error: Access denied (403) - Invalid credentials

Diagnosis:

# Test credentials with rclone directly
rclone lsd remote:bucket

# Check credential format and validity
rclone config show remote

Solutions:

  • Verify access keys are correct and not expired

  • Check if credentials have necessary permissions

  • For AWS S3, verify IAM policy allows required actions

  • Test credentials outside Borgitory first

Network Connectivity Issues

Error: Connection timeout or network unreachable

Diagnosis:

# Test network connectivity
ping google.com

# Test HTTPS connectivity
curl -I https://s3.amazonaws.com

# Check DNS resolution
nslookup s3.amazonaws.com

Solutions:

  • Verify internet connectivity

  • Check firewall rules allow outbound HTTPS

  • Configure proxy settings if behind corporate firewall

  • Verify DNS resolution works correctly

Bucket/Container Access Issues

Error: Bucket does not exist or access denied

Solutions:

  • Verify bucket/container name is correct

  • Check if bucket exists in specified region

  • Ensure credentials have access to the specific bucket

  • Review bucket policies and access controls

Performance Issues

Slow Backup Operations

Disk I/O Bottlenecks

Diagnosis:

# Monitor disk I/O
iostat -x 1

# Check disk usage patterns
iotop

Solutions:

  • Use SSD storage for repositories when possible

  • Avoid running multiple intensive operations simultaneously

  • Consider different compression algorithms (lz4 for speed, lzma for size)

  • Spread repositories across multiple disks

Network Performance Issues

Diagnosis:

# Test network speed
speedtest-cli

# Monitor network usage
iftop

# Test cloud provider connectivity
rclone test speed remote:

Solutions:

  • Choose cloud regions closer to your location

  • Use appropriate compression for your network speed

  • Consider bandwidth limiting during peak hours

  • Implement incremental backup strategies

High Memory Usage

Large Repository Memory Consumption

Diagnosis:

# Monitor memory usage
free -h

# Check process memory usage
ps aux --sort=-%mem | head

Solutions:

  • Increase available memory

  • Use checkpoint intervals to reduce memory usage

  • Split large repositories into smaller ones

  • For Docker, increase memory limits

Database Issues

SQLite Database Problems

Database Corruption

Error: Database disk image is malformed

Diagnosis:

# Check database integrity
sqlite3 data/borgitory.db "PRAGMA integrity_check;"

Solutions:

# Backup current database
cp data/borgitory.db data/borgitory.db.backup

# Attempt repair
sqlite3 data/borgitory.db ".recover" | sqlite3 data/borgitory_recovered.db

# Replace with recovered database
mv data/borgitory_recovered.db data/borgitory.db

# If repair fails, restore from backup
cp data/borgitory.db.backup data/borgitory.db

Database Lock Issues

Error: Database is locked

Solutions:

  • Stop Borgitory application

  • Check for zombie processes

  • Remove lock files if present

  • Restart application

Archive Browser Issues

FUSE Mount Problems

Archive Browser Disabled

Warning: Archive browsing disabled - FUSE not available

Solutions:

# For Docker deployment
docker run --cap-add SYS_ADMIN --device /dev/fuse ...

# For native installation, install FUSE
# Ubuntu/Debian:
sudo apt install fuse3

# Check FUSE kernel module
lsmod | grep fuse
sudo modprobe fuse

Warning

Windows Users: FUSE is not available on Windows systems. Archive browsing functionality requires FUSE and will not work with PyPI installation on Windows.

Recommended Solution: Use Docker installation on Windows, which provides a Linux environment where FUSE works properly:

docker run -d \
  --name borgitory \
  -p 8000:8000 \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  mlapaglia/borgitory:latest

Mount Permission Errors

Error: Permission denied mounting archive

Solutions:

  • Ensure user has permission to use FUSE

  • Add user to fuse group: sudo usermod -a -G fuse $USER

  • Check /etc/fuse.conf allows user mounts

  • Verify user_allow_other option is enabled

Web Interface Issues

Login Problems

Forgot Password

Solution:

# Reset admin password using CLI
borgitory reset-password admin

# Or recreate admin user
borgitory create-user admin --password newpassword --admin

Session Issues

Error: Session expired or invalid

Solutions:

  • Clear browser cookies and cache

  • Check system clock is correct

  • Verify secret key hasn’t changed

  • Restart Borgitory service

Connection Refused

Error: Connection refused to localhost:8000

Diagnosis:

# Check if service is running
ps aux | grep borgitory

# Check port binding
netstat -tlnp | grep 8000

# For Docker
docker ps
docker logs borgitory

Solutions:

  • Start Borgitory service

  • Check port configuration

  • Verify firewall allows port 8000

  • Check if another service is using the port

Getting Help

Collecting Debug Information

When reporting issues, include:

System Information:

# Operating system
uname -a

# Python version
python --version

# Borgitory version
borgitory --version

# Docker version (if using Docker)
docker --version

Application Logs:

# For PyPI installation
borgitory serve --log-level debug

# For Docker
docker logs borgitory

# Check system logs
journalctl -u borgitory

Configuration Details:

  • Sanitized configuration (remove sensitive data)

  • Repository setup information

  • Cloud provider configuration (without credentials)

  • Error messages with full stack traces

Support Channels

When reporting issues:

  1. Search existing issues first

  2. Provide detailed system information

  3. Include relevant log entries

  4. Describe steps to reproduce

  5. Mention any recent changes to your setup

Common Error Codes

HTTP Error Codes

  • 400 Bad Request: Invalid input data or configuration

  • 401 Unauthorized: Authentication required or failed

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Repository or resource doesn’t exist

  • 500 Internal Server Error: Application error (check logs)

Borg Exit Codes

  • 0: Success

  • 1: Warning (operation succeeded with warnings)

  • 2: Error (operation failed)

  • 3: Interrupted (operation was interrupted)

  • 4: Repository does not exist

  • 5: Repository already exists

Rclone Exit Codes

  • 0: Success

  • 1: Syntax or usage error

  • 2: Error not otherwise categorised

  • 3: Directory not found

  • 4: File not found

  • 5: Temporary error (retry may help)

  • 6: Less serious errors (like file skipped)

  • 7: Fatal error (don’t retry)

  • 8: Transfer exceeded - limit set by –max-transfer reached

  • 9: Operation successful, but no files transferred

Preventive Measures

Regular Maintenance

  • Monitor disk space regularly

  • Test restore procedures periodically

  • Update Borgitory to latest versions

  • Backup configuration and encryption keys

  • Monitor logs for warnings and errors

  • Verify repository integrity monthly

Best Practices

  • Use strong, unique passphrases

  • Implement 3-2-1 backup strategy

  • Test backups before relying on them

  • Monitor backup success rates

  • Keep documentation updated

  • Plan for disaster recovery scenarios