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-agent. Start it with sudo systemctl start rested-agent.
• 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 (running as its install user) can’t read a path or write the target. Adjust permissions or the configured paths.
• 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-agent ensure-restic on the server, then retry.

Still stuck?

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