Find and Fix Broken Links in WordPress

Broken links accumulate quietly: a renamed post here, a vendor documentation move there, an image removed during a redesign. Finding them is mechanical; deciding what each one should become is editorial and technical work. The status code alone cannot tell you whether to update a link, redirect an old URL, preserve a real 404, or retry a temporarily unavailable host.

What counts as broken

• A 404 or 410 can be correct when content has no replacement.

• A 301 or 308 is not broken, but internal links should usually point directly to the final URL.

• A 5xx, timeout, DNS error, 403, or 429 may be transient or scanner-specific.

• A page returning 200 with an error message can be a soft 404.

• Fragments such as #installation require checking the target element after the page loads.

• Images, scripts, stylesheets, downloads, embeds, canonical URLs, and structured data can break alongside ordinary anchors.

Back up and define the crawl boundary

• Take a restorable database backup and preserve wp-content before bulk edits.

• List production hostnames, languages, multisite sites, custom post types, private areas, and staging exclusions.

• Choose a polite concurrency and delay so scanning does not resemble an attack.

• Decide whether external URLs may be submitted to a cloud service; URLs can reveal private paths and editorial relationships.

• Create a small known-broken test page to confirm the scanner covers the content types you expect.

Option 1: use the Broken Link Checker plugin

1. Open Plugins → Add New and search for the exact WordPress.org listing and publisher.

1. Review compatibility, changelog, support history, data handling, and requested account connection.

1. Install and activate it on a backup-protected site.

1. Choose its local or cloud engine deliberately.

1. Configure post types, statuses, fields, exclusions, schedule, timeout, and notification settings.

1. Let the initial scan finish, then export or record findings before editing.

Local and cloud scans make different trades

• The local engine uses your WordPress server and can increase CPU, database work, and outbound requests.

• The cloud engine reduces origin load but sends crawl targets and results to a third-party service and may require an account.

• Either engine can be blocked by bot protection or remote rate limits.

• Disable and remove a plugin you no longer need, but retain the remediation report elsewhere.

• Keep any installed scanner updated like every other privileged WordPress plugin.

Option 2: crawl outside WordPress

An external crawler observes rendered public URLs without adding PHP work to WordPress. It is often better for theme navigation, generated archives, redirects, canonical tags, and assets. It may miss protected pages or block-editor data that is not rendered, so large sites commonly combine an external crawl with content-level inspection.

Validate suspicious responses manually

$ curl -sSIL --max-redirs 10 --connect-timeout 10 \
  --user-agent "Site link audit; contact=webmaster@example.com" \
  "https://example.org/old-page"

HTTP/2 301
location: https://example.org/new-page

HTTP/2 200

A response chain provides context

• -I requests headers, but some servers mishandle HEAD; retry with a normal GET before declaring failure.

• -L follows redirects and the maximum prevents loops.

• A descriptive user agent helps an external operator distinguish the audit from abuse.

• Do not bypass authentication, robots policy, rate limits, or access controls.

• Check the final content in a browser because a 200 can still be a soft 404.

Choose the right repair

• Internal page moved: update every internal source and add a server-side permanent redirect from the old URL.

• Internal page intentionally removed: remove or rewrite the source link and return a real 404 or 410 when no close replacement exists.

• External page moved: link directly to the authoritative new page.

• External source vanished: locate an equivalent authoritative source, rewrite the unsupported claim, or remove the link while preserving useful prose.

• Transient failure: retry later and avoid destructive edits based on one timeout.

• Broken fragment: update the anchor to an existing stable heading or remove only the fragment.

• Missing media: restore, replace, or remove the reference and regenerate responsive image metadata if necessary.

Avoid redirecting every missing URL to the homepage

A blanket homepage redirect frustrates people and can be treated as a soft 404. Google recommends a permanent redirect when a moved page has a clear replacement. When it does not, serve a useful custom error page with a genuine 404 status and navigation back into the site.

Use WP-CLI carefully for repeated replacements

$ wp search-replace 'https://example.com/old-doc' \
  'https://example.com/new-doc' wp_posts wp_postmeta --dry-run

Success: 12 replacements to be made.

Dry-run before mutating serialized WordPress data

• WP-CLI understands serialized data better than raw SQL replacement.

• Restrict tables and exact URLs to avoid changing unrelated text.

• --dry-run reports matches without saving; review every affected content type.

• For a real change, take a fresh backup, remove --dry-run, then clear caches and inspect representative pages.

• Multisite requires explicit site/network scope and separate verification.

Why automated checks report false positives

• The remote site blocks datacenter IPs or unknown user agents.

• A rate limit returns 429 during concurrent checks.

• A consent wall, geo rule, or authentication flow returns different content.

• TLS or DNS behaves differently over IPv6.

• JavaScript creates the final link or content after the scanner stops.

• The site rejects HEAD while GET succeeds.

• A temporary outage occurred during the scan.

Verify the repair

1. Purge WordPress, object, CDN, and browser caches as applicable.

1. Open every edited source page and exercise the link.

1. Check redirect chains and final status from outside the origin network.

1. Recrawl the same scope with the same settings.

1. Check Search Console’s Page Indexing and crawl reports for internal URL problems.

1. Update XML sitemaps, canonical links, menus, related-post modules, and structured data when URLs moved.

1. Keep a mapping of old URL, disposition, new URL, owner, and verification date.

Make link health routine

• Run a scheduled crawl at a frequency the site and external hosts can tolerate.

• Alert on new internal 4xx/5xx responses and redirect chains.

• Test important navigation and conversion paths in deployment CI.

• Require redirect mappings in the content-removal workflow.

• Offer a user-visible way to report a broken link.

• Review external references periodically because their ownership and content can change even while the URL returns 200.

Primary references

• Broken Link Checker on WordPress.org documents its current local and cloud engines, scope, and installation.

• WP-CLI search-replace documents serialized-data handling, table scope, exports, multisite, and --dry-run.

• Google crawl-error guidance distinguishes moved content, true 404 pages, and soft 404s.

• Google redirects guidance describes server-side permanent redirects for moved URLs.