After a SharePoint site URL change, tenant rename, or cross-tenant migration, every absolute URL embedded in site pages, navigation links, and list columns becomes stale. The pages load, but the links within them point at addresses that no longer exist.
Manually hunting down every stale link across dozens of sites and hundreds of pages is not practical. This guide explains where broken URLs accumulate, how to scope the problem, and how to fix them in bulk using Replace Master.
Why do URLs break in SharePoint Online?
A SharePoint URL breaks whenever the domain or path it references no longer matches the current location of the content. This happens most often after three specific events: a tenant rename, a site URL change, and a cross-tenant migration. Each one invalidates a different segment of every absolute URL stored in your environment.
After a SharePoint tenant rename
When a Microsoft 365 tenant is renamed (for example, from contoso.sharepoint.com to newbrand.sharepoint.com), every absolute URL in every page, every list item, and every embedded link that references the old domain becomes a dead link. Microsoft provides a temporary redirect from old URLs to the new domain for a period after the rename, but the redirect is not permanent and cannot be relied on indefinitely. The only durable fix is replacing the old domain string with the new one, everywhere it appears.
After a site URL change
Renaming a site collection, changing its managed path (from /sites/old-marketing to /sites/marketing), or moving it to a different site address changes the canonical URL for all content within that site. Any absolute link from another site pointing to a page, file, or list in the renamed site will break immediately. Relative links within the site itself usually survive, since they reference paths below the site root rather than the full URL.
After a cross-tenant migration
Moving site collections between tenants as part of a merger, acquisition, or divestiture always changes the domain component of every URL. Unlike a tenant rename, there is no redirect at all: the source and destination tenants are entirely separate Microsoft 365 environments with no link between them. Update all absolute links on both sides manually or in bulk before decommissioning the source tenant.
Where broken URLs hide in a SharePoint tenant
Obvious broken links surface quickly - a page author notices a failed hero image the moment they view the page. The harder-to-find ones are embedded deep in structured content, where they go unnoticed for weeks or months until someone actually follows the link.
These are the locations where absolute URLs accumulate:
- Site pages and news posts: Text web parts, Quick Links web parts, Button web parts, Hero web parts, and Image links all store target URLs in the page metadata. A richly designed Communication Site homepage may contain dozens of distinct link targets.
- Global navigation and Quick Launch: Navigation links in SharePoint sites are often configured with absolute URLs rather than relative paths, particularly when linking across sites or to external resources. These do not show up in a search of page content.
- List and library hyperlink columns: Hyperlink or Picture column types store a URL value per item. A library with 5,000 items all linking to the old tenant domain requires 5,000 individual updates if done manually.
- List text and multi-line text columns: Columns of type Single line of text or Multiple lines of text that happen to contain URLs are updated by Replace Master if the old pattern matches.
- Managed metadata and calculated columns: These are generally not patchable by Replace Master and require manual review if they contain URL patterns.
- Inside Office documents: Hyperlinks within the body of a Word document, Excel workbook, or PowerPoint presentation are stored inside the file itself, not in SharePoint metadata. Replace Master does not modify file content and these must be updated by opening each document.
Scoping the problem before you start
Before running any replacement, map out which locations are patchable automatically and which require manual attention. Attempting to fix everything at once without a plan leads to missed items.
| Location type | Replace Master can fix | Action required |
|---|---|---|
| Site pages and news posts | Yes | Include in Replace Master scope; review results after run |
| List hyperlink columns | Yes | Include in scope; use library or list-level scoping for large item counts |
| List text columns containing embedded URLs | Yes | Include in scope; confirm column is indexed for search if the list is large |
| Quick Launch navigation links | No | Update manually via Site Settings or the SharePoint admin centre |
| Global navigation (hub sites) | No | Update manually in the hub site navigation settings |
| Links inside .docx, .xlsx, .pptx files | No | Open each document individually; use Find and Replace in the Office application |
| Links inside PDF files | No | Regenerate PDFs from source documents after fixing document-internal links |
Also clarify the scope of the pattern change. A tenant rename requires replacing the entire domain string across all site collections. A single site rename may only require updating links in sites that contained cross-site references to the renamed site. Scoping Replace Master to a smaller set of sites reduces run time and keeps the change log easier to review.
Finding and replacing broken URLs with Replace Master
Replace Master scans SharePoint site pages, lists, and libraries for any occurrence of a text pattern and replaces it with a string you specify. For URL replacement after a rename or migration, the pattern is the old URL prefix and the replacement is the corresponding new URL prefix. You do not need to enumerate every unique link; provide the common prefix once and Replace Master updates every URL built on it in a single pass.
For a full comparison of what Replace Master offers versus the native SharePoint find-and-replace experience, see Replace Master vs SharePoint's native find and replace.
Step 1: Define your scope
Connect Replace Master to your Microsoft 365 tenant and select the site collections or individual sites to include in the operation. For a tenant rename affecting all sites, select the full tenant scope. For a single site rename, scope to the sites most likely to contain cross-site links pointing to the old URL; this is usually the sites closest to the renamed site in the site hierarchy, plus any hub sites that linked to it.
Step 2: Enter the find and replace pattern
In the Replace Master find/replace interface, enter:
- Find: the old URL prefix (e.g.,
https://contoso.sharepoint.com/sites/old-marketing) - Replace: the new URL prefix (e.g.,
https://contoso.sharepoint.com/sites/marketing)
For a tenant rename, the find pattern is the old base domain (https://oldtenant.sharepoint.com) and the replacement is the new base domain (https://newtenant.sharepoint.com). Replace Master performs a substring match, so every URL that begins with, contains, or ends with the old string is caught in the same pass.
Step 3: Preview changes before applying
Replace Master generates a preview list of every match before writing any changes. Each result shows the site, the page or list item, the matched text in context, and the proposed replacement. Review the list carefully before proceeding. Deselect any results you want to skip, such as items in archived sites or libraries where the old URL is intentionally preserved as a historical reference.
Step 4: Execute the replacement and review the log
Run the job. Replace Master writes the updated content to each selected item and records an outcome (success or failure) for each one. Review the log when the job completes. Failures typically indicate permission issues on the item or items that were modified by another user during the run. Address failures individually.
Learn more about Replace Master
Updating navigation links manually
Quick Launch and global navigation links are not scanned by Replace Master. They are stored in the site's navigation settings rather than in list item or page metadata, and they must be updated through the SharePoint interface.
For Quick Launch links on a standard site:
- Go to Site Settings (the gear icon > Site settings, or Settings > Site information > View all site settings).
- Under Look and Feel, select Navigation.
- Edit each navigation node that uses the old URL and update the URL field.
For hub site global navigation, the same process applies on the hub site itself. Changes to hub navigation propagate to associated sites, so updating the hub site navigation once is enough for the sites connected to it. Sites with custom local navigation set through the SharePoint admin centre may need to be updated separately in the admin portal under Active sites.
Preventing URL rot in future migrations
/sites/Marketing/Documents/policy.pdf rather than https://contoso.sharepoint.com/sites/Marketing/Documents/policy.pdf). Relative links survive site renames within the same tenant because they reference a path below the site root rather than an absolute address. Absolute links are unavoidable for cross-site references, but keeping them out of single-site content reduces the cleanup burden significantly after any future restructure.
A few other practices reduce URL rot over time:
- Document absolute URLs before you migrate. Before any tenant rename, site move, or cross-tenant migration, export a report of active sharing links and navigation links from the affected sites. This gives you a known starting point for the replacement pass.
- Run Replace Master as a post-migration validation step. Treating URL replacement as part of the standard migration sign-off checklist prevents the problem from quietly accumulating while users encounter dead links sporadically over the following weeks. The SharePoint cross-tenant migration guide covers the full migration workflow including post-migration cleanup.
- Communicate the new URLs to site owners. Site owners and page editors often maintain their own lists of internal links in word processors or personal notes. After a rename, send them the new URL base and a reminder to update any links they maintain outside SharePoint itself.
Frequently Asked Questions
Can I use SharePoint search to find broken links across my tenant?
SharePoint search indexes content but does not identify broken links as a distinct category. You can search for the old URL string and find pages that contain it, but each result would require a manual edit to fix. This works for fewer than ten affected pages; it is impractical for tenants where the old URL pattern appears in hundreds or thousands of list items and site pages. Use Replace Master for any migration or rename that touches more than one or two sites.
Does Replace Master update links inside Word or Excel files in SharePoint?
No. Replace Master operates on SharePoint metadata, site page content, and list item column values. It does not open or modify the content inside Office documents (.docx, .xlsx, .pptx) or PDF files. Hyperlinks embedded in the body of a Word document or an Excel cell formula must be updated by opening each file individually and using the application's own find-and-replace feature.
What if the renamed tenant still redirects old URLs?
Microsoft maintains a redirect from old tenant URLs to the new address for a period after a rename. Relying on this redirect as a long-term fix carries risk: the redirect may eventually be removed, and users see a URL mismatch in their browser address bar that erodes trust in the links they follow. Updating all embedded links to the new address as part of the migration removes the dependency on a temporary redirect you do not control.
How long does a Replace Master URL scan take for a large tenant?
Run time depends on the number of sites, pages, and list items in scope. For tenants with hundreds of site collections and thousands of pages, a full scan may take several minutes. Scoping the operation to specific site collections or sites significantly reduces run time. For very large tenants, running the replacement in batches by site collection keeps each individual job manageable and makes the change log easier to review.