Backup Issues

Troubleshooting backup and restore problems.

Solutions to common backup and restore problems in Supascale.

Backup Creation Issues

"Insufficient disk space"

Error:

{
  "success": false,
  "error": "Backup failed: Insufficient disk space"
}

Solutions:

Check available space:
```
df -h
df -h ~/.supascale_backups/
```

Free up space:

# Remove old backups
ls -la ~/.supascale_backups/
rm -rf ~/.supascale_backups/old-backup.tar.gz

# Clean Docker
docker system prune -a

Change backup destination:
- Use cloud storage instead of local
- Mount additional storage
Use incremental backups instead of full backups

Backup Stuck at "Creating"

Problem: Backup stays in in_progress state indefinitely.

Diagnostic:

# Check if backup process is running
ps aux | grep pg_dump
ps aux | grep tar

# Check disk I/O
iostat -x 1

Solutions:

Check database accessibility:
```
docker compose exec db pg_isready
```
Cancel stuck backup via API or restart Supascale
Check for locked files:
```
lsof | grep supascale_backups
```

"Database connection failed"

Error:

{
  "success": false,
  "error": "Backup failed: Database connection error"
}

Solutions:

Verify project is running:

cd ~/supabase/projects/your-project
docker compose ps

Check database container:
```
docker compose logs db
```

Test database connection:

docker compose exec db psql -U postgres -c "SELECT 1"

"Permission denied"

Error:

{
  "success": false,
  "error": "Permission denied: Cannot write to backup directory"
}

Solutions:

Check directory permissions:
```
ls -la ~/.supascale_backups/
```

Fix permissions:

chmod 755 ~/.supascale_backups/
chown -R $(whoami) ~/.supascale_backups/

Check SELinux/AppArmor (if applicable):

getenforce
# If enforcing, check audit logs
ausearch -m AVC -ts recent

Cloud Storage Backup Issues

S3 Upload Failed

Error:

{
  "success": false,
  "error": "Failed to upload to S3: Access Denied"
}

Solutions:

Test credentials:
```
aws s3 ls s3://your-bucket/
```
Check IAM permissions: Required permissions:
- s3:PutObject
- s3:GetObject
- s3:DeleteObject
- s3:ListBucket
Verify bucket exists and is in correct region
Check bucket policy allows access from your IP

GCS Upload Failed

Error:

{
  "success": false,
  "error": "Failed to upload to GCS: Forbidden"
}

Solutions:

Verify service account permissions:
- roles/storage.objectAdmin on bucket
Check credentials JSON is valid and not expired
Test with gsutil:
```
gsutil ls gs://your-bucket/
```

Azure Blob Upload Failed

Error:

{
  "success": false,
  "error": "Failed to upload to Azure: AuthorizationFailure"
}

Solutions:

Verify account name and key

Check container exists:

az storage container list --account-name youraccountname

Check network rules if using private endpoints

Connection Timeout

Error:

{
  "success": false,
  "error": "Connection timeout to cloud storage"
}

Solutions:

Check network connectivity:

# For S3
curl -I https://s3.amazonaws.com

# For GCS
curl -I https://storage.googleapis.com

Check firewall rules for outbound HTTPS
Use regional endpoint instead of global
Increase timeout settings

Restore Issues

"Backup not found"

Error:

{
  "success": false,
  "error": "Backup file not found"
}

Solutions:

Check backup still exists:
```
ls -la ~/.supascale_backups/
```
For cloud backups, verify file in bucket
Backup may have been deleted - check backup retention policy

Restore Stuck or Failing

Problem: Restore process hangs or fails midway.

Solutions:

Check project status:
- Project should be stopped during full restore
- Some partial restores work while running
Check available disk space:
```
df -h
```

Manually restore:

# Extract backup
tar -xzf backup.tar.gz

# Restore database
docker compose exec -T db psql -U postgres < database.sql

"Database version mismatch"

Error:

{
  "success": false,
  "error": "Backup was created with PostgreSQL 15, current version is 14"
}

Solutions:

Upgrade project PostgreSQL to match backup version
Use --compatible flag if available
Manually edit dump file to remove version-specific features (not recommended)

Partial Restore Failures

Problem: Some components restore while others fail.

Solutions:

Check warnings in response:

{
  "warnings": [
    "Some functions could not be restored"
  ]
}

Restore components individually:
- Try database-only restore first
- Then storage
- Then functions
Check dependencies:
- Extensions must be enabled
- Required schemas must exist

Scheduled Backup Issues

Scheduled Backups Not Running

Problem: Cron backups not executing.

Diagnostic:

Check task is enabled in Scheduled Tasks
Check last run time and status
Check system logs for errors

Solutions:

Verify task configuration:
- Correct cron expression
- Correct timezone
- Task enabled
Check Supascale is running during scheduled time
Run task manually to test:
```
POST /api/v1/tasks/:id/run
```

Missing Backups

Problem: Fewer backups than expected.

Common causes:

Backup retention policy deleting old backups
Scheduled task disabled
Failures not reported

Solutions:

Review backup history in Supascale
Check task execution history
Adjust retention policy if needed

Data Recovery

Recovering from Corrupted Backup

# Try to extract
tar -xzf backup.tar.gz 2>&1 | head

# If tar is corrupted, try recovery
gzip -d backup.tar.gz
tar -xf backup.tar --ignore-zeros

Point-in-Time Recovery

For critical data, consider:

Enable PostgreSQL WAL archiving
Set up continuous backup to cloud storage
Configure shorter backup intervals

Performance Issues

Backups Taking Too Long

Optimization:

Use incremental backups when possible
Exclude unnecessary data:
- Large binary files
- Temporary tables
- Cached data
Run during low-traffic periods
Use faster storage for backup destination
Compress efficiently:
- Use gzip for balance of speed/size
- Use lz4 for faster compression

Impact on Production

Minimize backup impact:

Use snapshot-based backups if available
Replicate to read replica and backup from there
Schedule during maintenance windows

Getting Help

When reporting backup issues, include:

Backup configuration:
- Type (full, database, storage)
- Destination (local, S3, GCS, etc.)
Error message from Supascale
Backup logs from system logs
Storage status:
```
df -h
```

Cloud storage status (if applicable):

# Test connectivity
aws s3 ls s3://your-bucket/