This article explains where to find your link remediation results, what each figure means, and what to do about the most common failures. For what the feature does, see Link remediation.
Where to find your results
Results appear in three places.
- A Link Remediation panel on the migration progress page, showing the totals for the whole migration while it runs.
- A Link Remediation section in the migration report, both in the overall report and in each user's report.
- The document mapping CSV attached to the migration report, which lists every source file and where it now lives. This is what to use when you want to check an individual link by hand.
The panel and the report section only appear on migrations where link remediation actually ran and found something. On a normal document migration, they are not shown.
What the figures mean
| Figure | Meaning |
|---|---|
| Scanned | Links inspected. Every link the pass looked at, whether or not it needed changing. |
| Found | Links identified as pointing at your source. Shown in the per-user report only. |
| Mapped | Links matched to a file that has migrated, so a destination is known. |
| Replaced | Links actually rewritten on this run. |
| Already replaced | Links that already pointed at the destination, so nothing needed doing. |
| Users with no links | Users the pass ran for and found nothing to remediate. Shown in the overall report only. |
A Replaced by type table breaks the replaced figure down into Docs, Sheets, Slides, Folders and Other. Other covers links to file types that are not one of the first four, and links where the file type could not be determined, which is normal for URLs found inside spreadsheet formulas.
On a completed run, Scanned should reconcile against Replaced plus Already replaced plus the links that could not be matched.
Reading a second run
The figures are recalculated from your documents on every run. They are not carried forward. So the same migration run twice produces two very different-looking sets of numbers, and both are correct:
- First run. Links get rewritten, so Mapped and Replaced are close to Scanned, and Already replaced is zero or near it.
- Second run over the same documents. The links now point at the destination, so Mapped and Replaced are zero or near it, and almost everything counts as Already replaced.
A second run showing Replaced as zero is the pass telling you there was nothing left to do. It is not a failure.
Why Scanned can look higher than you expect
Scanned counts links, not files. A spreadsheet that links to the same document from thirty cells contributes thirty scanned links. This is consistent between runs, so it does not affect whether your figures reconcile, but it means Scanned is not a count of distinct documents.
Why the item count is lower than your document migration
A link remediation pass does not go back over everything that migrated. It only opens the file types that can contain a link it is able to rewrite:
- Google Workspace source. Google Docs, Sheets and Slides.
- Microsoft 365 source. Word, Excel and PowerPoint files.
Everything else in the drive is skipped at the point of listing, not opened and passed over. PDFs, images, video, folders and every other file type are never counted, because there is nothing inside them the pass can change. Files in the trash are excluded too, and on a user's own My Drive only the files that user owns are included — a file shared into their Drive by someone else is handled on that owner's pass instead, so it is processed once rather than once per person who can see it.
So the item count on a link remediation run is expected to be a long way below the item count on the document migration that preceded it, often a small fraction of it. That gap is the pass working as intended, not files being missed.
The same applies to the size figures. A link remediation pass reports no data migrated, because it rewrites links inside documents that are already at the destination rather than transferring content.
The Documents row says Link parsing
In the breakdown by data type, a link remediation run shows a Link parsing row where a document migration would show Documents. Link remediation counts each file it opens and checks, but no file content is transferred, so the row is relabelled to make clear that the number is files checked rather than data moved. This is why the size migrated for a link remediation pass is zero.
Checking an individual document
Each document processed has a per-item result with a detail line like this:
Scanned: 42 | Google Drive: 30 | Mapped: 28 | Replaced: 28 (Docs: 20, Sheets: 8) | Already replaced: 2 | Unmapped: 3 (IDs: ...)Where links could not be matched, or need fixing by hand, the file identifiers are listed. The first ten are shown, then a count of the rest.
Troubleshooting
A user fails immediately with "No link mappings found for this user"
Cause. That user has no record of migrated documents, so there is nothing to match links against. Usually the document migration has not been run for them, or it was run into a different destination.
Resolution. Run the document migration for that user, confirm it completes, then run link remediation again.
Every document fails with an authorisation or permission error
Cause. The three additional Google API scopes are missing, or the Docs, Sheets and Slides APIs are not enabled on your Google Cloud project. Drive access alone does not allow the contents of a Google Doc to be edited.
Resolution. Add the scopes and enable the APIs as described in Set up and run link remediation, then re-run. This is the single most common cause of a whole pass failing.
To confirm before re-running, use Test Connection on your Google destination connection and check that the Docs (Link Parser), Sheets (Link Parser) and Slides (Link Parser) checks pass. A warning on any of the three means the scope or the API is still missing.
Documents report "No existing item located"
Cause. The source file was found, but its migrated copy could not be located in the destination. The file did not migrate, or it was moved or deleted in the destination afterwards.
Resolution. Check the file in your document migration results. If it failed there, fix that first. Link remediation cannot repoint a link at a file that is not there.
Documents report "Item not in this Shared Drive"
Cause. The file exists in the destination but sits in a different shared drive from the one being processed.
Resolution. Check that your migration items point at the right shared drives, and that the file was not moved after migration. The detail on the item names the drive the file was actually found in.
Documents report "Skipped, unsupported type"
Cause. The destination file is an Office format that cannot be rewritten in place, such as .docm, .xlsm, .doc or .xls. Only .docx, .xlsx and .pptx can be edited as binaries, alongside native Google Docs, Sheets and Slides.
Resolution. If the links in these files matter, either convert the documents to Google format during the document migration and re-run remediation, or fix the links by hand.
A Microsoft 365 user reports that document libraries could not be enumerated
Cause. Microsoft Graph refused access to the site. Where the Azure AD application holds the Sites.Selected role, access has to be granted for each individual site.
Resolution. Grant the application access to the site, then re-run. The failure message names the drive and says whether Graph returned Forbidden.
Links are reported as unmapped
An unmapped link is one that was recognised as pointing at your source, but could not be matched to a migrated file. It is left untouched. Common reasons:
- The target file was not part of the migration, so there is no migrated copy to point at.
- The target file belongs to a user who has not been migrated yet. Migrate them, then re-run remediation.
- The target is a file type that was not part of the document migration, such as a file left behind by a content type filter.
A Google Sheets cell still shows the old address
Cause. The cell holds a single Drive URL inside a sentence, with no hyperlink you applied yourself. In that one shape the visible text is left as it was, while the cell link is pointed at the migrated file.
What this means. Clicking the cell opens the correct migrated document. Only the address written in the text is stale. No link is broken and nothing needs re-running.
Resolution. None needed for the link to work. If the written address matters, for example because people copy it out of the sheet rather than clicking it, edit those cells by hand. A cell holding two or more URLs, or a URL on its own, is updated in the text as well, so this only affects the single-URL-in-a-sentence shape.
Links are listed as needing manual action
Cause. The link is a chip in a Google Doc, or a non-Drive smart chip in a Google Sheet. Google's API does not allow the target of these to be changed.
Resolution. Use the file identifiers listed on the item result to find them, then replace the chips by hand in the destination documents.
Documents show as modified on the migration date
Cause. The Preserve Modified Date setting is off, so Google's own timestamp from the rewrite is kept.
Resolution. Turn the setting on before your next remediation pass. It is on by default. Dates already changed cannot be restored retrospectively.