Common Issues

Connection Refused

failed to connect to server: connection refused

Causes: Server not running, wrong address, or firewall blocking port 50051.

# 1. Verify server is running
sudo systemctl status backup-server
ps aux | grep "xreplicator server"
 
# 2. Check agent config matches server address
# storage.grpc.server_address: "192.168.1.100:50051"
 
# 3. Test connectivity
telnet 192.168.1.100 50051
nc -zv 192.168.1.100 50051
 
# 4. Open firewall port
sudo ufw allow 50051
# or
sudo firewall-cmd --add-port=50051/tcp --permanent
sudo firewall-cmd --reload

License Validation Failed

FATAL: License validation failed

# Check license file exists
ls -la /var/lib/backup/repo/license.json
 
# Verify hostname matches
hostname
 
# Inspect license content
cat /var/lib/backup/repo/license.json | jq .
 
# Check environment for public key
echo $LICENSE_PUBLIC_KEY

See Licensing for detailed resolution steps.

Slow Backup Speed

Symptoms: Backup taking too long, low throughput.

# Check throughput in logs
sudo journalctl -u backup-agent | grep "Throughput"
 
# Test raw network bandwidth
iperf3 -c backup-server-ip

Solutions:

For single-server SQLite deployments, avoid starting several initial full backups at the same time. Start with one or two concurrent full backups, then increase only after checking server CPU, disk I/O, and network headroom.

# Increase batch size and workers
daemon:
  pipeline:
    batch_size: 400
    workers: 8
  compression:
    level: 1   # Fastest compression

Multiple Full Backups Are Running Slowly

Symptoms: Several VMs start initial full backups together and each backup runs much slower than a single backup.

Causes: The backup server, repository disk, and metadata backend are shared resources. Initial full backups are the heaviest workload because they read, send, index, and store a large amount of data at once.

What to do:

• Limit initial full backups to a small number per backup server.
• Stagger first-time backups across maintenance windows.
• Keep server.max_concurrent_backup_streams set in single-server installs.
• Use faster repository disks before increasing agent workers.
• For larger estates, use the PostgreSQL/object-storage deployment model and benchmark it with your storage and network before production rollout.

server:
  max_concurrent_backup_streams: 2

Backup Stuck In Progress

Symptoms: A backup remains in receiving data, pausing, or another in-progress state after an agent crash, network interruption, or server restart.

What to check:

sudo journalctl -u backup-agent -f
sudo journalctl -u backup-server -f
xreplicator snapshots --server localhost:50051

If the agent is healthy, retry or resume the backup from the UI or CLI. If the job is stale and cannot be resumed, use the repository maintenance command provided for your metadata backend, then restart the backup server.

xreplicator repository --config /etc/xreplicator/server.yaml stale-jobs
xreplicator repository --config /etc/xreplicator/server.yaml stale-jobs --execute
sudo systemctl restart backup-server

Run the first command as a dry-run. Use --execute only after confirming the agent is not still uploading.

Do not edit repository database files manually unless support asks you to do so.

Failed Or Partial Backup Cannot Be Deleted

Symptoms: A failed backup remains visible, deletion fails, or a partial restore point appears after an interrupted backup.

What to do:

• Prefer deleting failed restore points from the Web UI.
• If UI deletion fails, check the backup server logs before retrying.
• Run repository maintenance in dry-run mode before cleanup when available.
• Do not remove repository files or edit database rows manually.

Backup data can be shared between restore points. Manual deletion can break a later healthy restore point even when the failed restore point looks unrelated.

High Memory Usage

Symptoms: Daemon using excessive RAM.

daemon:
  pipeline:
    batch_size: 100
    max_pipeline_memory_mb: 1024
    max_io_queue_depth: 5
    channel_buffer_mult: 2
    workers: 2

Snapshot Not Found

snapshot not found: <id>

# List available snapshots
xreplicator snapshots --server localhost:50051
 
# Check snapshot directory
ls -la /var/lib/backup/repo/snapshots/
 
# Retrieve specific snapshot
xreplicator snapshots --server localhost:50051 --id <snapshot-id>

Verification Or Restore Uses The Wrong Snapshot

Symptoms: Verification or restore is attempted against a restore point that is still in progress, or the selected snapshot is not yet available.

Only completed restore points should be used for restore or verification. Wait until the backup is marked complete/available, refresh the Backups page, and select the completed restore point. If an in-progress restore point remains visible after an interruption, follow Backup Stuck In Progress above before running verification.

Cloud Sync Finds No Targets

Symptoms: Cloud Sync logs show messages such as no matching targets or no target mappings configured.

Cause: The service is reading the wrong cloud config path, or the target_mappings section does not match the protected host/device.

xreplicator cloud-sync \
  --repo /var/lib/backup/repo \
  --cloud-config /etc/xreplicator/cloud-config.yaml \
  --dry-run=true

For scheduled jobs, make sure the systemd timer or cron entry includes the same --cloud-config path used in manual tests.

Diagnostic Commands

Service Status

sudo systemctl status backup-agent
sudo systemctl status backup-server

# Windows agent service
Get-Service XReplicatorAgent

Viewing Logs

# Individual services
sudo journalctl -u backup-agent -f
sudo journalctl -u backup-server -f
 
# All backup services at once
sudo journalctl -u backup-* -f

# WinSW logs
Get-Content "C:\ProgramData\xreplicator\logs\XReplicatorAgent.err.log" -Tail 200
Get-Content "C:\ProgramData\xreplicator\logs\XReplicatorAgent.out.log" -Tail 200

Testing Connectivity

# Basic TCP test
telnet backup-server-ip 50051
 
# gRPC reflection (if enabled)
grpcurl -plaintext backup-server-ip:50051 list

Resource Usage

# CPU and memory
top | grep xreplicator
 
# Disk I/O
iotop | grep xreplicator
 
# Network
nethogs

Validating Config

cat /etc/xreplicator/agent.yaml
yamllint /etc/xreplicator/agent.yaml

Performance Tuning Reference

High Bandwidth (1 Gbps+)

daemon:
  pipeline:
    batch_size: 400
    workers: 8
  compression:
    enabled: true
    level: 1

Low Bandwidth (10 Mbps)

daemon:
  pipeline:
    batch_size: 20
    workers: 2
  compression:
    enabled: true
    level: 3

Memory-Constrained (1 GB Limit)

daemon:
  pipeline:
    max_io_queue_depth: 3
    channel_buffer_mult: 2
    max_pipeline_memory_mb: 1024
    workers: 2
    fixed_block_size_mb: 8
  compression:
    enabled: true
    level: 1

High Performance (4 GB+ Available)

daemon:
  pipeline:
    max_io_queue_depth: 20
    channel_buffer_mult: 8
    max_pipeline_memory_mb: 4096
    workers: 8
    fixed_block_size_mb: 16
  compression:
    enabled: true
    level: 1