Skip to content

Troubleshooting

Common issues with the agent and backups, and how to resolve them.

The agent shows as offline

A server is “offline” when it hasn’t checked in recently. On the server:

  • Confirm the service is running: systemctl status rested. Start it with sudo systemctl start rested.
  • Check the agent can reach Rested (outbound HTTPS). Firewalls or lost network are the usual cause.
  • If the server was revoked or re-installed, generate a new enrollment token from its page and re-run the install command.

A backup failed

Open the repository to see the failure and a log excerpt. Common causes:

  • Permission denied — the agent service runs as root, but mounted filesystems, container permissions, ACLs, or a protected restore target can still block access. Check the configured paths and the repository logs before changing permissions.
  • Disk full — free space on the server, or on the restore target when restoring.
  • Database connection failed — for database recipes, make sure the database or container is running and the configured host, port, and credentials are correct.
  • Wrong credentials — a storage or database credential changed. Update it in the repository configuration.

restic is not installed

The agent downloads and pins a verified restic binary during install. If a backup reports restic missing, re-run the installer or sudo rested ensure-restic on the server, then retry.

The snapshot list is empty

Snapshots appear after the first successful backup and after the agent reports them back. If the list looks empty:

  • Confirm at least one backup has completed successfully in the repository's history.
  • Press Refresh on the Snapshots tab while the agent is online, so it can list the repository and report what it finds.
  • If runs are failing before any snapshot is written, resolve the backup failure above first — there is nothing to list until one succeeds.

A backup is unexpectedly large or slow

restic deduplicates data, so size and duration usually settle after the first run:

  • The first backup uploads a full copy of the selected paths. Later runs only send changed chunks, so they are smaller and faster.
  • Exclude caches, build output, and temporary directories you do not need to recover — they inflate every backup.
  • A run that keeps growing usually means large files are changing between backups (logs, database data directories). Back up a database dump instead of its live data files where you can.

Still stuck?

For recovery-specific questions — including restoring without the original machine — see Recovery & your encryption key.