This article explains how to retry only the items that failed during a migration, rather than re-running entire users or the whole batch. Retry failed items was introduced in CloudM Migrate 5.1.
When items fail during a migration, CloudM Migrate records each failed item. You can then re-run just those items, so a small number of failures does not mean reprocessing everything that already migrated successfully.
Supported migrations
Retry failed items is currently available for:
- Source platforms: Google Workspace and Microsoft 365
- Item types: Email and Drive files (documents)
Failed items of other types, or from other source platforms, cannot be retried yet. Support will be expanded in future releases. The next section lists everything a retry run does not cover.
What is not retried
Retry only covers failures that CloudM Migrate recorded against an individual email or file. Some failures are never retried, and for those you need to re-run the affected users in full instead.
If a failure is not retried, use Start migration for failed users or Restart migrate item to re-run the affected users.
Failures that happen before an individual item
If a migration cannot get as far as processing individual items, there is nothing for a retry run to pick up. This includes:
- Connection and authentication failures, including expired or revoked credentials.
- Permission and licence errors on the source or destination account.
- Failures listing folders or mailboxes.
- Any error that stops a whole user from migrating.
These still appear as failures in the migration report, but they are not recorded as failed items, so a retry run does not include them.
Folders
Only emails and files are retried. A folder that failed to create is not, so a folder-level failure needs a full re-run of the user.
Item types other than email and Drive files
Calendars, contacts, tasks, sites, Teams and chat items are not retried, even when the retry option is available for the batch. Their failures still appear in the migration report.
Users and workloads that are no longer enabled
Failed items are only retried for users that are still enabled for migration, with the matching workload still switched on. If you disable mail for a user, their failed emails are not retried.
Items that cannot succeed
Retry does not distinguish between temporary failures, such as throttling, and permanent ones. Every recorded failed item is attempted again. An item that can never succeed, for example a file that has since been deleted from the source, fails on every retry and keeps appearing in the report. Check the failure reason in the migration report before retrying the same items repeatedly.
Retry failed items for the whole migration
After a migration has completed, you can start a new run that processes only the items that failed.
Steps:
- Go to the Progress page for your migration batch.
- Click the arrow on the Start migration button to open the dropdown menu.
- Select Start migration for failed items.
The migration starts a new run in which each user only re-attempts their own failed items. Items that migrated successfully are not reprocessed.
For this option to be available:
- The most recent migration run must have completed.
- The batch configuration settings must not have changed since that run. If you have changed settings, revert them to retry, or run a full migration instead.
- There must be at least one failed item of a supported type, belonging to a user that is enabled for migration.
Retry failed items during a migration
While a migration is still running, you can retry the failed items for users that have already finished with a Warning status, without waiting for the rest of the batch.
For all users
Steps:
- On the Progress page, click the Restart users dropdown above the migration list.
- Select Retry failed items for all users.
- Confirm the retry. Failed items are retried for every user currently in a Warning state.
For a single user
Steps:
- On the Progress page, find the user whose failed items you want to retry.
- Click on the ellipsis to the right hand side of that user.
- Select Retry failed items from the action menu.
Retry failed items compared to other restart options
| Option | What it does |
|---|---|
| Start migration for failed items | After a migration has completed, starts a new run that re-attempts only the individual items that failed. Successful items are not reprocessed. |
| Retry failed items for all users | During a running migration, re-attempts the failed items for every user in a Warning state. |
| Retry failed items (single user) | During a running migration, re-attempts the failed items for one user in a Warning state. |
| Start migration for failed users | Re-runs the full migration for every user that failed. |
| Restart migrate item | Re-runs the full migration for a single user. |
If the option is unavailable
When Start migration for failed items is greyed out, hover over it to see why. The possible messages are:
| Message | What it means |
|---|---|
| Retry failed items is not enabled for this environment. | The feature is not switched on for your environment. Contact CloudM Support. |
| Retrying failed items is only available after a migration has completed. | Wait for the current run to complete. This also appears if the last completed run took place on a version earlier than 5.1. |
| The migration configuration settings have changed since the last run, please revert the settings to initiate a retry. | Retry re-uses the configuration of the completed run. Revert your settings changes, or run a full migration with the new settings. |
| Retrying failed items is not supported for this platform. | The source platform is not yet supported. See Supported migrations above. |
| There are no failed items to retry. | The last run recorded no failed items. |
| None of the failed items can be retried for the current migration item settings. | Failed items exist, but none belong to a user and item type that is currently enabled for migration. Check the mail and drive workloads are still enabled for the affected users. |