Troubleshooting¶
This article explains common reasons for backup and recovery failures and warnings, and provides guidance on troubleshooting and resolving these issues.
How to view and check tasks with Failed or Warning status¶
If any task for a tenant finishes with a Failed or Warning status during a 7-day period, the Backup statuses chart in the Overview dashboard will display a non-zero number of failures or warnings. You can configure service reports on the Configuration → Reports tab to receive periodic emails or Slack/Teams/Google Chats notifications with licensing and protection/backup status updates for a tenant.
To find tasks affected by a failure or a warning, please go to the Activity → Tasks tab and filter tasks with Failed or Warning statuses, after that you can view details for each task by clicking on it and review the failure reason or the affected items in case of a warning.
Backup and recovery failures¶
Most common backup failures:
| Error | Reason |
|---|---|
| Not authorized | The Afi application hasn't been granted permissions to back up the user.
Please check if the Afi application is installed for the entire Google Workspace tenant, which is a recommended configuration, and not for specific organizational units/groups. If you still prefer to install the application only for specific organizational units/groups, please ensure that the affected users are present in these units/groups. |
| The attempted action requires shared drive membership | The Afi application doesn't have access to any active (not suspended/archived) Manager or Content Manager member of the Shared drive.
Please ensure that the Afi application is installed for the entire Google Workspace tenant or that, at least, it is installed for one of the Manager or Content Manager members of the Shared drive. |
| Quota exceeded | The Afi tenant exceeds its licensed user or storage quota.
Please go to the Licensing → Subscriptions tab to review the available quota and the current service usage or adjust the license counts according to the usage. |
Most common recovery failures:
| Error | Reason |
|---|---|
| Not authorized | The Afi application hasn't been granted permissions to access the restore destination user.
Please check if the Afi application is installed for the entire Google Workspace tenant, which is a recommended configuration, and not for specific organizational units/groups. If you still prefer to install the application only for specific organizational units/groups, please ensure that the affected users are present in these units/groups. |
| Not authorized | The Afi application hasn't been granted permissions to at least one active Manager/Content Manager in the restore destination Shared drive.
Please ensure that the Afi application is installed for the entire Google Workspace tenant or that, at least, it is installed for one of the Manager or Content Manager members of the Shared drive. |
| User not found Shared drive is not found |
The restore destination user/Shared drive doesn't exist on the Google Workspace side at the moment.
A typical scenario in which this error occurs is when you back up a resource, delete it on the Google side, and then attempt to perform an overwrite restore for that resource. Since Afi doesn't recreate users or Shared drives upon a recovery, it will fail with the corresponding error. In such cases we advise to firstly manually recreate a restore destination user/Shared drive on the Google side, trigger a resources discovery in the Afi portal on the Service → Protection screen by clicking on the refresh icon in the top-right corner and, when the discovery is finished, select a newly created user/drive as a restore destination. |
Backup and recovery warnings¶
In rare cases a backup task can finish with a warning when it fails to download one or more items (files, emails, etc.) from Google Workspace. The common reason why it happens is the following:
| Error | Reason |
|---|---|
| Can't download file due to API errors, probably it is corrupted, will retry later. | The file is likely corrupted and can't be retrieved through Google API.
In this case we suggest to try opening the file through Google Drive user interface, most certainly it will fail with some kind of 500 Server Error. To resolve the issue, you can replace the corrupted file in Google Drive with a correct copy from one of the previous backups. If the affected file is a native Google Drive Document, Spreadsheet, or Presentation, you can convert it from a Google native document to a Microsoft 365 office file (DOCX, XLSX, PPTX) as in some cases Google API doesn't allow to export large Google native documents with complex formatting. |
Paused backups or restores¶
A common reason for a paused backup is Google Workspace API throttling during the initial data synchronization for a resource (user, Shared drive). When the Afi service detects an elevated rate of transient errors Google Workspace, it pauses the affected task and automatically restarts it in a few hours. Upon restarting, the task resumes from the saved state and continues the synchronization. Paused backups typically do not require manual troubleshooting, as API throttling issues are usually resolved by themselves within a few hours. After the initial data synchronization for the Google Workspace tenant is complete, subsequent incremental backups are expected to be fast and run without disruptions, regardless of the resource size.
In rare cases, a backup or recovery task may be paused due to an accidental, non-throttling-related error from Google Workspace. In such instances, the task will pause in a similar manner and generally finish successfully after an automatic restart by the service. The Afi team continuously monitors paused tasks across our customer base and proactively investigates and resolves recurring issues.