Docs / Troubleshooting / Backup Failed Playbook

Backup Failed Playbook

Published · Last updated: May 2026 · 3 min read

Who this is for

Users whose backup has failed or whose scheduled backup has not run.

Step 1 — Check the Error Message

  1. Go to Server detail → Backups tab.
  2. Find the failed backup (status failed).
  3. Expand the backup entry or click it to see the error message.

The error is stored on the backup record and also visible in the Activity Center.

Step 2 — Diagnose by Error Type

SSH Errors

Error: SSH_NOT_CONFIGURED

Error: Connection refused / Connection timed out

Error: Permission denied (publickey)

  • CloudAIPilot's key is not in authorized_keys.
  • Fix: Re-add the public key. See KB-02-08.

Disk Space Errors

Error: No space left on device

  • The server's disk is full. Backup files are written to /tmp/cloudpilot-backups/.
  • Fix:
  1. Delete old backups from the Backups tab to free disk space.
  2. Or resize the server's disk — see KB-02-10.
  3. Reduce retention days to auto-expire old backups faster.

Configuration Errors

Error: INVALID_CONFIG

  • The offsite cloud storage config does not exist or is invalid.
  • Fix: Remove the offsite config from the backup and try again, or verify the storage vault — see KB-05-07.

Backup Stuck in "running"

If a backup has been running for more than 30 minutes:

  1. Check the Activity Center for the last logged step.
  2. Check server disk space: the backup job may be filling the disk and hanging.
  3. Check if the SSH session dropped mid-backup.

To recover:

  1. On the server, check for stuck processes: ps aux | grep cloudpilot
  2. Kill the stuck process: sudo kill
  3. Clean up partial backup: sudo rm -rf /tmp/cloudpilot-backups/
  4. Delete the failed backup record in CloudAIPilot.
  5. Create a new backup.

Step 3 — Retry the Backup

After fixing the root cause:

  1. Go to Server detail → Backups tab.
  2. Click + Create Backup (or trigger a new on-demand backup with the same type).

Scheduled Backups Not Running

If you notice no new backups are appearing from your schedule:

  1. Go to Backups → Schedules tab.
  2. Verify the schedule is active (not paused/deleted).
  3. Check the Next run time — ensure the schedule is still valid.
  4. Check if the last run attempt failed — it appears in the Backups list with trigger: scheduled.
  5. Verify the cron expression is correct (use https://crontab.guru).
  6. Verify the server was online during the scheduled time.

Related Articles