Docs / Backups & Restore / Backup Troubleshooting Checklist

Backup Troubleshooting Checklist

Published · Last updated: May 2026 · 4 min read

Who this is for

Users who have encountered a backup error, a failed backup, a failed restore, or are unsure why backups are not running.

Quick Diagnostic Checklist

Before diving into specific errors, check these basics:

Error Code Reference

Backup Creation Errors

Error codeMeaningFix
SSH_NOT_CONFIGUREDNo SSH key is set for this serverAdd an SSH key — see KB-02-08
INVALID_TYPEUnknown backup type specifiedUse snapshot, files, database, or full only
INVALID_SITEThe selected site does not belong to this serverSelect a site that exists on this server
INVALID_CONFIGThe offsite config ID does not exist or does not belong to this orgVerify the storage vault configuration
BACKUP_IN_PROGRESSTrying to delete a backup that is currently runningWait for it to complete first

Restore Errors

Error codeMeaningFix
INVALID_STATEBackup is not completedOnly completed backups can be restored
SNAPSHOT_RESTORETrying to restore a snapshot via CloudAIPilotUse the cloud provider console — see KB-05-05
RESTORE_IN_PROGRESSAnother restore is already running on this serverWait for it to finish, or cancel it — see KB-05-06

Download Errors

Error codeMeaningFix
NOT_COMPLETEDBackup is not in completed stateWait for backup to finish
SNAPSHOT_NOT_DOWNLOADABLESnapshot backups cannot be downloadedUse cloud provider console
NO_BACKUP_DIRBackup directory not found on serverServer may have been rebuilt; use offsite copy if available
INVALID_PATHAttempted to access a file outside the backup directoryUse only paths shown in the File Browser
DOWNLOAD_FAILEDSSH/stream error while downloadingRetry. Check SSH connectivity.

Offsite Upload Errors

Error codeMeaningFix
NOT_COMPLETEDBackup not yet completedWait for backup to complete first
SNAPSHOTSnapshot type cannot be pushed offsiteUse file/database/full backups for offsite storage
MISSING_CONFIGNo cloud storage config ID providedSelect a storage vault
NO_DIRBackup directory missing on serverRun a new backup
INVALID_CONFIGCloud storage config not found or inaccessibleVerify the storage vault settings

Backup Stuck in "running" or "pending"

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

  1. Check the Activity Center for error output.
  2. SSH into the server and check: ls /tmp/cloudpilot-backups/
  3. Check if the server has disk space: df -h
  4. Check if a backup script process is running: ps aux | grep cloudpilot

If the process is stuck:

  1. Kill the stuck process on the server.
  2. Delete the failed backup record in CloudAIPilot.
  3. Create a new backup.

Backup Completed but File is Unexpectedly Small

Possible causes:

  • Site backup targeted a site with no files in its document root.
  • Database backup found no tables or the database is empty.
  • Incremental backup found no changes since the last backup (this is normal — the file will be very small).

Scheduled Backups Not Running

  1. Verify the schedule is active (not paused).
  2. Verify the cron expression is correct using a cron validator tool (e.g., https://crontab.guru).
  3. Check if the server was offline during the scheduled time — missed runs are not retried.
  4. Check the last run time and next run time shown in the schedule list.

Offsite Upload Stuck at "uploading"

  1. Check if the cloud account credentials are still valid.
  2. Check bucket permissions — CloudAIPilot needs s3:PutObject (AWS), storage.objects.create (GCP), or equivalent write permissions.
  3. Delete the stuck backup record and create a new backup with offsite upload enabled.

Related Articles