Broken internal links after a WordPress migration: how to fix them

Redirects catch external traffic from Google and bookmarks. Internal links are how your own site navigates — and after a WordPress rebuild, links that still point at old paths create redirect chains, waste crawl budget, and add latency on every click. Worse, links hard-coded to the old domain bypass your new permalink structure entirely. Fixing internal links is not optional polish; it is part of a finished migration.

Why internal links break on rebuilds

The problem is rarely 'someone forgot a menu item'. It is systemic — URLs stored in dozens of places across the database, only some of which appear in the visual editor.

• arrow_rightAbsolute URLs in post content and block fields still reference the old domain.
• arrow_rightPermalink structure changed (/blog/post-name/ vs /post-name/) but content was not rewritten.
• arrow_rightPage-builder link attributes stored URLs in post meta, not in visible post_content.
• arrow_rightNavigation menus rebuilt manually with one or two items still pointing at staging or old paths.
• arrow_rightACF link fields and button blocks contain the old URL in sub-fields the importer did not touch.
• arrow_rightFooter widget text and theme options hold links outside any single post.

How to find every broken internal link

Run a full crawl on staging with Screaming Frog, Sitebulb or similar. Export all internal links and their response codes. You are looking for three failure modes:

1. 1404 — link points at a URL that does not exist on the new site.
2. 2301/302 chain — link points at old path that redirects to new path (should be direct 200).
3. 3Wrong domain — link still uses https://oldsite.com/ absolute URLs.

Compare crawl results against your redirect map. If an internal link hits a redirect rule, update the link to the final destination URL.

Where links hide (beyond post_content)

Fix at migration time, not after launch

Post-launch search-replace is stressful and incomplete. Build link rewriting into the import pipeline.

1. 1Build URL mapping table: old path → new path for every page that moved.
2. 2During import, rewrite links in post_content and all ACF block fields.
3. 3Export and rebuild menus — or run menu URL search-replace with staging backup.
4. 4Crawl staging; filter internal links that return 301 — target zero.
5. 5Post-launch: second crawl at week one per post-launch monitoring.

Search-replace plugins: limits and risks

Better Search Replace and WP-CLI search-replace handle simple domain swaps when old and new strings are the same length — or when using tools that understand serialised PHP data. They fail when:

• arrow_rightPath changes alter serialised string lengths and corrupt meta if done naively.
• arrow_rightLinks live in JSON-encoded block attributes with escaped slashes.
• arrow_rightMultiple environments (staging.domain.com) need different rules than production.
• arrow_rightLink fields store URL, title and target as separate serialised keys.

Always run on staging, full database backup first, and verify ACF block fields page by page on high-traffic URLs. Pair with broken images checks in the same crawl pass.

Measuring success

Before launch, your crawl should show:

• arrow_rightZero internal links to old-domain absolute URLs.
• arrow_rightMinimal internal links hitting redirect rules — ideally none on navigation and body CTAs.
• arrow_rightAll menu items return 200 on final URLs.
• arrow_rightTop 20 traffic pages: manual click-test of every in-content link.

If more than a handful of internal links rely on redirects, the migration is not finished — you are shipping latency and crawl inefficiency into production.

Internal links and SEO

Internal links distribute PageRank-style authority and help crawlers discover pages. After a migration, Google must recrawl your new structure. Direct links speed that process; redirect chains slow it and dilute equity passed between pages.

This work sits inside the broader SEO rebuild checklist. Redirects protect external signals; direct internal links protect on-site architecture.

Crawl-and-map migrations

A structured migration pipeline rewrites links in the same pass as image sideloading and ACF field population — using the URL map from inventory stage. That is preferable to import-then-fix because field-level links are handled consistently. See how to migrate to ACF blocks and AI-assisted migration for pipeline context.

WP-CLI and database approaches

For simple domain changes on identical path structures, `wp search-replace 'https://old.com' 'https://new.com' --all-tables` on staging is fast — with the serialised data caveat. Always run `--dry-run` first. For path changes (/blog/ prefix removal), prefer URL-map-driven import rewriting over blind replace — one wrong replace corrupts widget serialisation.

Link equity and redirect chains (technical)

Google's documentation has long noted that redirects dilute signal compared with direct links. For internal navigation, the user experience cost is also real: each 301 in a chain adds round trips. Marketing pages with ten internal links through redirect rules load measurably slower than direct links. Fix chains before launch, not when Lighthouse flags them.

Staging vs production link checks

On staging, internal links may still reference production domain if content was cloned before rewrite. Run link crawl after URL rewrite pass, not before. After production launch, run a third crawl — some plugins generate absolute production URLs only after go-live.

Reporting link fixes to clients

Export before/after crawl metrics: internal 404 count, internal redirect count, absolute old-domain link count. Clients rarely ask about internal links until SEO dips — showing zero old-domain links pre-launch builds confidence and justifies migration line item cost.

Edge cases

• arrow_rightAnchor-only links (#section) — usually fine if parent page URL updated.
• arrow_rightmailto: and tel: links — should not change during migration.
• arrow_rightDownload links to PDFs in uploads — verify files migrated and paths updated.
• arrow_rightExternal links accidentally pointed at staging — common after clone.
• arrow_rightPagination links (/page/2/) — update when permalink structure changes.

Building the URL map for link rewrite

The URL map is the single source of truth for both redirects and internal link rewriting. Columns: old absolute URL, old path, new path, new absolute URL, redirect needed (Y/N), notes. Populate from crawl export joined with client sitemap decisions. During ACF import, every link field and anchor href should resolve against this table — longest path match first so /services/consulting/ wins over /services/. Export the map to CSV and version-control it; link fixes during QA often reveal map gaps that need redirect rows too.

Automation vs manual link QA

Automated rewrite handles ninety percent of links in post content and ACF fields when the URL map is complete. Manual QA handles navigation edge cases, footer legal links hard-coded in theme options, and CTAs in reusable blocks. Assign link QA to someone with Screaming Frog literacy — not the same person running import if possible. Fresh eyes catch staging.domain.com links left in button blocks.

Internal links in reusable blocks and patterns

Synced patterns and reusable Gutenberg blocks multiply link errors — one wrong CTA URL in a pattern breaks every page using it. After link rewrite, inventory all patterns and block template parts separately from page crawl.

ACF options pages sometimes store global footer links outside post tables. Export options table rows containing http and grep for old domain — tedious but necessary on sites with marketing-owned global CTAs.

Link QA in the migration QA checklist

Treat internal link crawl as a hard gate in pre-launch QA — same priority as redirect spot-checks. Export Screaming Frog internal links report filtered to 3xx and 4xx; attach to launch ticket. Zero is the target for 4xx internal; 3xx internal should be under five on large sites and zero on nav plus footer. Re-run after client content editors have one week on staging — they add links faster than you fix them. Post-launch week one crawl catches production-only URL generation bugs from SEO plugins.

Add internal link crawl to your monthly retainer health check for six months post-migration — editors reintroduce old-domain links in blog posts routinely.

Summary

Fix internal links during import with a URL map, verify with crawl before launch, re-crawl week one. Redirects are for outsiders; your site should link directly. ACF fields and menus are where manual migrations fail — check them explicitly.

Train content editors post-migration: use relative links or the link picker, not pasted full URLs from the old site PDFs and email campaigns. One lunch-and-learn prevents hundreds of broken blog links over the following year.

Collaboration with content and SEO teams

SEO owns URL map accuracy. Developers own rewrite implementation. Content owns post-launch link habits. Without those three roles named, internal links regress within a quarter.

Add a quarterly Screaming Frog internal link export to SEO retainer for the first year after migration — cheap insurance on large sites.

Export Screaming Frog redirect chains report alongside internal link report — chains often reveal link fixes you still owe as well as redirect rules to simplify.

Internal link health is a leading indicator of migration quality — share crawl metrics in the client handover deck alongside Lighthouse and redirect counts.

Links, redirects, and menus — three related jobs

Internal link rewrites and 301 redirects overlap but are not the same — fix links in content to point at final URLs; use redirect map for URLs that changed. Navigation menus break silently: menu migration. AIRA rewrites links in imported bundles; manual passes still need QA checklist on high-traffic pages.