OneDrive for Business file server migration troubleshooting for weekend cutovers: breaks recent links

When migrating file servers to OneDrive for Business during a weekend cutover, users often report that links shared from the old server no longer work. These broken links lead to access denied errors or file-not-found messages, disrupting workflows immediately after the migration. The root cause is that the cutover changes the file path or URL structure, and the shared links still point to the original server location instead of the new OneDrive path. This article explains why those links break, provides a step-by-step method to prevent the issue before the cutover, and describes how to fix links that are already broken.

Why File Server Migration Breaks Shared Links

When you migrate files from a network file server to OneDrive for Business, the underlying file path changes from a UNC path, such as \fileserver\shared\Project\Report.docx, to a OneDrive URL like https://contoso-my.sharepoint.com/personal/user/Documents/Project/Report.docx. Any link that was shared from the file server contains the original UNC path. After the cutover, the file server is taken offline or its share permissions are modified, so those UNC paths become unreachable.

The SharePoint Migration Tool does not automatically update existing shared links during the migration process. It copies files and metadata but leaves the old links intact. The cutover itself, typically performed over a weekend, introduces a gap where users expect the migrated files to be accessible via the old links but find them broken.

The role of the cutover window

A weekend cutover means the file server is decommissioned or its shares are disabled on Friday evening, and users are expected to access files through OneDrive starting Monday morning. During that window, no one can update links. If the migration is not configured to preserve or redirect links, every shared URL from the old server becomes invalid.

Steps to Prevent Broken Links Before the Cutover

Follow these steps in the week before the cutover to minimize or eliminate broken shared links.

1. Run a pre-scan with the SharePoint Migration Tool
   Open SPMT and create a new migration job for the file server share. On the “Scan” step, select “Full scan” and enable “Analyze shared links.” The tool generates a report listing every shared link that will break. Export this report to CSV for remediation planning.
2. Notify link owners of pending breakage
   Use the CSV report to identify the original creator of each link. Send an automated email from the Microsoft 365 admin center or a PowerShell script that lists the exact files whose shared links will break. Instruct owners to re-share those files from OneDrive after migration.
3. Configure link redirection in SPMT
   In SPMT settings, under “Advanced,” enable “Redirect shared links to new location.” This option creates a URL redirect from the old file server path to the new OneDrive URL. The redirect works only if the old server remains accessible during the cutover. If the server is fully decommissioned, this setting has no effect.
4. Test the migration on a subset of files
   Create a test share on the file server with 20 to 50 files. Run a trial migration to OneDrive using SPMT with the redirect option enabled. After the trial, verify that shared links on those test files resolve to the OneDrive URLs. Adjust settings before the full cutover.

How to Fix Links That Are Already Broken After the Cutover

If the cutover is complete and users report broken links, use these methods to repair them.

1. Use the SharePoint Admin Center link repair tool
   Go to Microsoft 365 admin center > SharePoint > Migration > Link repair. Click “Start scan” to identify all broken shared links in the tenant. The tool lists each broken link along with the target file path in OneDrive. Select the links and click “Repair” to update them to the OneDrive URL.
2. Repair links with PowerShell
   Open SharePoint Online Management Shell as administrator. Run Connect-SPOService -Url https://contoso-admin.sharepoint.com. Then run Repair-SPOSiteGroup -Identity "https://contoso-my.sharepoint.com/personal/user" -OldUrl "\\fileserver\shared" -NewUrl "https://contoso-my.sharepoint.com/personal/user/Documents". This command replaces all occurrences of the old UNC path in shared links within the specified OneDrive site.
3. Ask users to manually re-share files
   For a small number of broken links, instruct users to open the file in OneDrive, click the Share button, and create a new sharing link. They must then send the new link to anyone who received the old one. This method is time-consuming but works when the admin tools cannot find the broken links.

If Shared Links Still Fail After Repair

Broken links point to a file that was not migrated

Check the SPMT migration report to confirm the file was included. If the file was excluded because of file type blocking or size limits, the link cannot be repaired. Add the file to a new migration job and run it again. Then repeat the link repair step.

Users see “Access denied” on repaired links

The repair tool updates the URL but does not change permissions. Verify that the external sharing settings in OneDrive allow the intended recipients. Go to Microsoft 365 admin center > SharePoint > Policies > Sharing and ensure “Anyone” or “New and existing guests” is selected as needed. If the original link was shared with specific people, those people must be added to the OneDrive file sharing permissions again.

Repaired links open the wrong file

This occurs when the migration renamed files or placed them in different folders. Review the SPMT mapping file to ensure the source and destination paths match exactly. If a file was moved to a different folder after migration, you must manually update the link or move the file back to the expected location.

Item	Pre-cutover prevention	Post-cutover repair
Tool used	SharePoint Migration Tool pre-scan	SharePoint Admin Center link repair or PowerShell
Time required	Several days before cutover	Hours to days after cutover
Success rate for link preservation	High if redirect is enabled and server stays online	High for identified links, low for unknown links
User involvement	Link owners must re-share proactively	Users may need to re-share if repair fails

You now know why file server migration during a weekend cutover breaks OneDrive shared links and how to prevent or repair them. Before your next cutover, run the SPMT pre-scan with link analysis and enable the redirect option. After the cutover, use the SharePoint Admin Center link repair tool or the Repair-SPOSiteGroup PowerShell command to fix broken URLs. For files that were not migrated, run a targeted migration job and then reapply the repair.