Fix failed records after a migration¶
When a migration run ends with Completed with Errors or Failed, find out which records failed and why, fix the cause, and process them again, without uploading anything twice.
When to use this
A run on Media Migration Runs shows Failed records, or its status is Failed because it was interrupted or cancelled.
1. Read the migration log¶
- Open Media Migration Runs and select the run.
- Choose Migration Log.
- Choose Show Failed Only to see only the failed records. Choose Show All to see every record again.
| Column | Meaning |
|---|---|
| Entity | Item, Item Variant or Employee. |
| Record Key | A readable name, such as the item description. It stays readable after the record is deleted. |
| Record ID | The record. Choose the value to open it. |
| Status | Transferred, Skipped, Failed or Source Delete Failed. |
| Error Message | Why the record failed. |
| Ext. File Path | The file written to External File Storage, if any. |
| Processed At | When the record was last processed. |
Each record appears once per run. A retry or resume updates the existing line.
1.1. Typical error messages¶
| Message | Likely cause | What to do |
|---|---|---|
| Failed to read picture from external file storage: ... | The file is missing from the storage account, or access was refused. | Check the file and the account's permissions. |
| The picture could not be read from Tenant Media; the referenced media no longer exists. | The record points to a picture that was deleted from the database. | Upload the picture again, or delete it on the record. |
| Failed to upload picture to external file storage: ... | The target storage refused the file. | Test the connection and check the account's permissions. |
| The source picture could not be read from the source storage. | Generic read failure, without more detail. | Open the record and check its picture. |
| The picture could not be written to the target storage. | Generic write failure, without more detail. | Test the connection. |
| The picture was transferred, but the source copy could not be deleted. | Status Source Delete Failed. The target is fine. | No action needed for the picture. The next migration to External File Storage with Delete Source After Transfer tries to remove the source copy again. |
| The record no longer exists and was skipped. | The record was deleted after the run. | Nothing to do. |
2. Retry the failed records¶
Use this when only a few records failed and you fixed the cause.
- In the Migration Log of the run, choose Retry Failed.
- Confirm with Yes.
Media Bridge processes only the failed records of that run, with the run's original options. A record that was deleted in the meantime is set to Skipped. When no failed records remain, the run becomes Completed and the storage source switches to the target.
3. Resume a run¶
Use this when a run stopped halfway, for example because it was cancelled or its background job crashed.
- Open Media Migration Runs and select the run. Resume Run is available for runs with status Failed or Completed with Errors.
- Choose Resume Run and confirm with Yes.
Media Bridge goes through all records with a picture in the source again, with the run's original options, and:
- skips records already Transferred, Skipped or Source Delete Failed in this run;
- processes records that Failed, records the run never reached, and records created since the run started.
Retry Failed or Resume Run?
Retry Failed only looks at the failed lines and is fast. Resume Run scans the whole catalogue again and also picks up records the run never reached. After an interruption, use Resume Run.
Both actions run in the foreground, from the page.
4. Verify¶
- The run's Failed counter is 0 and its status is Completed.
- Media Bridge Setup shows the target as Media Storage Source.
5. Common signals you may need this procedure¶
Migration run %1 cannot be resumed because its status is %2.
Only Failed and Completed with Errors runs can be resumed. A run that is still In Progress must be cancelled first. See Cancel a stuck run.
The record no longer exists, so it cannot be opened.
You chose a Record ID of a record that was deleted.
6. When to contact The Framework¶
- The same records keep failing after you fixed the cause.
- The error message doesn't match any of the causes above.