Troubleshooting · Troubleshooting
How to Fix Broken Links After a Migration in WordPress
Short answer
Fix broken links after a WordPress migration by first correcting the home and siteurl values, then running a serialization-safe search-replace that swaps the old domain for the new one in posts, options and metadata. After that, save permalinks again, clear every cache, and click through menus, images and key pages to confirm each link now points to the new domain.
Key takeaways
- The old domain stays in the database after a move, so links, images and settings still point to it until you replace it.
- A plain SQL replace can corrupt serialized settings, so use WP-CLI search-replace or Better Search Replace instead.
- Never change the guid column, because WordPress treats it as a permanent identifier for each post.
- Better Search Replace version 1.4.11, released June 29, 2026, requires WordPress 6.2 or later and PHP 8.1 or later.
- Save Settings then Permalinks again after a move to rebuild the rewrite rules in .htaccess.
- Back up the database before any search-replace, because a wrong string cannot be undone without a backup.
What does a broken link after a migration mean?
A broken link after a migration is a link, image or redirect that still points to the old domain, the old folder or the old http address instead of the new one.
WordPress stores full URLs in posts, options, widgets and plugin settings, so those saved values do not change on their own when the files move.
The WordPress handbook says that when a domain or URL changes, references to the old domain stay in the database and can cause issues with links or theme display (Migrating WordPress). That is why a moved site can look fine on the home page yet show dead links inside posts.
Why do links break after a migration?
Links break after a migration most often because the old domain is still stored in the database.
The causes below run from most likely to least likely, so check them in this order.
| Cause | Where it hides | Typical symptom |
|---|---|---|
| Old domain in the database | Posts, options, postmeta | Internal links open the old domain |
| Wrong home or siteurl | wp_options table | Site redirects to the old address |
| Stale cache | Plugin, server or browser cache | Fixed links still look broken |
| Broken permalinks | .htaccess rewrite rules | Posts return 404 errors |
| Hard-coded theme links | sidebar.php, footer.php | Menu or footer links point to the old domain |
| Old SSL or http links | Post content, widgets | Mixed content warnings or http links |
How do you find every broken link after a migration?
Search the database for the old domain before you change anything, so you know how far the problem reaches.
Start with a backup. Make a full copy of the files and database first, and keep it somewhere safe, because a search-replace cannot be undone without one.
Then run a dry run. A dry run reports how many fields would change without saving anything, and both WP-CLI and Better Search Replace offer one. Use the count to judge whether the old domain appears in a few posts or across the whole site.
Check the places a database search can miss: menus under Appearance then Menus, widgets under Appearance then Widgets, and links typed by hand into theme files such as sidebar.php and footer.php.
How do you fix the site address and home URL first?
Correct the two address settings first, because they control where WordPress thinks the site lives.
WordPress stores two addresses as rows in the wp_options table: Site Address (URL), called home, is the address visitors type, and WordPress Address (URL), called siteurl, is where the core files live. On most sites they match.
Both settings should include the https:// part and should not have a slash at the end, according to the WordPress migrating handbook. A trailing slash or a missing https can send visitors to the wrong address.
If you can reach the dashboard, go to Settings then General and type the new address in both fields, then click Save Changes. If you cannot reach the dashboard, add two lines to wp-config.php above the line that says stop editing:
define( 'WP_HOME', 'https://example.com' );
define( 'WP_SITEURL', 'https://example.com' );
Replace example.com with your own domain. The handbook warns that these lines hard-code the values, so you cannot edit them on the General settings page while they are in place.
You can also fix the values with WP-CLI. The handbook gives these two commands, with your own domain in place of example.com:
wp option update home 'https://example.com'
wp option update siteurl 'https://example.com'
How do you run a safe search-replace with Better Search Replace?
Use Better Search Replace when you have no command-line access, because it handles serialized data from the dashboard.
Better Search Replace is a free plugin on WordPress.org that offers serialization support for all tables, table selection and a dry run (Better Search Replace). Its page warns that a wrong search or replace string can damage the database, so back up first.
Version 1.4.11, released June 29, 2026, requires WordPress 6.2 or later and PHP 8.1 or later, as of November 2026.
Follow these steps in order:
- Install and activate Better Search Replace from Plugins then Add New.
- Go to Tools then Better Search Replace.
- Type the old address in Search for and the new address in Replace with, with no trailing slash on either.
- Select every table that starts with your table prefix, which is wp_ by default.
- Leave Run as dry run checked and click Run Search/Replace.
- Read the per-table counts, then uncheck the dry run box and run it again.
Repeat the pass for each form of the old address you find, such as http and https versions, or with and without www. One pass only fixes the exact string you typed.
After the replace, the plugin page says you may need to regenerate .htaccess by going to Settings then Permalinks and saving the settings. Do that before you judge the result.
How do you fix broken links with WP-CLI search-replace?
Use WP-CLI search-replace when you have SSH access, because it is fast and handles serialized data.
The WP-CLI docs say the command searches rows in selected tables and replaces the first string with the second, and that it intelligently handles PHP serialized data and does not change primary key values (wp search-replace). Tables without a primary key are skipped.
Run a dry run first, then the live run:
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --skip-columns=guid --dry-run
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --skip-columns=guid
The --skip-columns=guid flag protects the guid column, which must never change. The handbook gives the same example with example.dev and example.com.
Add --all-tables-with-prefix when plugin tables hold old URLs, because the default run only covers tables registered to WordPress. For complex serialized data, add --precise, which forces PHP to process all columns instead of fast SQL queries.
Avoid --regex unless you need it. The WP-CLI docs warn that search-replace runs about 15 to 20 times slower with --regex, as of November 2026. A plain string replace covers a domain change.
For a Multisite install, add --network to cover all sites in the network. The docs say that without it, only the tables for the current site are covered.
Why does a plain SQL replace break serialized data?
A plain SQL replace breaks serialized data because it changes the text without updating the length number stored with it.
Serialized data is a format WordPress uses to store settings, widgets and page builder layouts as text. Each string inside it carries its exact character count, so a URL change that adds or removes characters makes the stored count wrong.
The WordPress handbook warns that a search and replace on the whole database can cause serialization issues, because some themes and widgets store values with the length of the URL marked (Migrating WordPress). When the count is wrong, WordPress cannot read the setting and may drop it.
That is why the handbook lists three safe options: a plugin such as Better Search Replace, WP-CLI search-replace, or the Search and Replace for WordPress Databases script. Each one unserializes the value, changes the URL, writes the new length and serializes it again.
How do you fix permalinks, cache and .htaccess after the replace?
Reset permalinks and clear every cache after the replace, because old rewrite rules and cached pages can hide a fix that already worked.
Go to Settings then Permalinks and click Save Changes without changing the structure. Duplicator's migration guide says this step automatically regenerates the .htaccess file (How to Fix Your WordPress Site Not Working After a Migration).
If the .htaccess file itself is corrupt, rename it to .htaccess_old through your host file manager or FTP, then save permalinks again to build a fresh one. Keep a copy of any custom redirects from the old file first.
Clear the caches in this order: your caching plugin, your host server cache, your CDN cache if you use one, and your browser cache. Duplicator lists clearing cache and server-side caching as the first post-migration step, because cached pages can show old site versions.
Flush the object cache after a WP-CLI replace. WordPress VIP docs say to run wp cache flush before you review the front end, so stale cached values do not mask the new URLs (Use WP-CLI search-replace).
If posts still return 404 errors, read the guide on fixing 404 errors on posts before changing anything else. A 404 after a move usually points to permalinks, not missing content.
How do you fix links in menus, widgets and page builders?
Check menus, widgets and builder data by hand, because some of them store URLs outside post content.
Open Appearance then Menus and look for any custom link that still shows the old domain. The handbook says links to your home page in menus may still hold the old subdirectory, so update them there.
Open Appearance then Widgets and check text, image and custom HTML widgets. The handbook lists widgets as one of the places that need revision after a move, along with the upload path and plugin settings in wp_options.
Also check the footer, header and sidebar template files for typed links. The handbook says to search each template file for hand-entered references to the old domain and replace them with the new one.
If images are still missing while links work, the files may not have moved. A full backup before the move matters here: if you need a refresher on that step, see how to back up WordPress.
How do you check the fix worked?
Click through the site as a visitor and search the database again for the old domain.
Work through this checklist, and stop when every item passes:
- Open the home page, 5 posts, 5 pages and the main menu on the new domain.
- Click every link in the header, footer and sidebar.
- Open the Media Library and confirm images load from the new domain.
- Log in to wp-admin at the new address and open Settings then General.
- Run the search-replace dry run again and confirm it finds 0 matches for the old domain.
- Check the site on a phone and in a private browser window to dodge cache.
Duplicator's post-migration checklist advises clicking through main navigation, footer links, sidebar widgets and internal content links to catch 404 errors and check http and https consistency (Post-Migration Testing Checklist).
When should you contact your host?
Contact your host when the database, DNS or SSL setup blocks the fix, or when the site stays down after the steps above.
Ask the host for help in these cases:
- You cannot reach phpMyAdmin, SSH or the file manager to edit wp-config.php.
- The database login in wp-config.php does not match the new database, user or password.
- DNS still points to the old server after the waiting time your host states.
- The SSL certificate does not cover the new domain, so browsers show a warning.
- The site shows a database connection error after you checked the login details.
Duplicator notes that an invalid SSL certificate often follows a domain change, because certificates link to the domain name, and your host can issue a new one (How to Fix Your WordPress Site Not Working After a Migration).
Before you call, write down the old domain, the new domain, the exact error message and the last step you ran. That list lets support check DNS, the database and the certificate without guessing.
If the move used Duplicator and the import itself failed, see how to migrate WordPress with Duplicator.
If the move used UpdraftPlus instead, see how to migrate a site with UpdraftPlus.
What mistakes should you avoid?
The most common mistake is running a live replace without a backup or a dry run.
Avoid these errors:
- Changing the guid column, which WordPress treats as a permanent post identifier.
- Using a plain SQL REPLACE on the whole database, which corrupts serialized settings.
- Replacing only the https form of the old domain and leaving http links behind.
- Leaving WP_HOME, WP_SITEURL or RELOCATE hard-coded in wp-config.php after the fix.
- Skipping the permalinks save and cache clear, then judging the fix too early.
- Editing theme files on the live site without a copy of the original.
The handbook is blunt: never, ever change the contents of the guid column, under any circumstances. Changing it makes feed readers show old posts as new.
BlogVault notes its tool rewrites URLs as the site moves, serialized data included, and Migrate Guru moves sites as large as 200 GB, as of November 2026 (WordPress migrations).
Frequently asked questions
How long does it take to fix broken links after a migration?
A small site often takes under an hour: correct the two address settings, run one dry run and one live search-replace, save permalinks and clear caches. A large site with page builder data, many widgets and hard-coded theme links takes longer, because each of those places needs its own check. Run the dry run first so you can judge the size of the job before you start.
Can I fix broken links without WP-CLI or a plugin?
You can fix the two address settings by hand in Settings then General or in wp-config.php, and you can fix menus and widgets by hand in the dashboard. For links inside post content and settings, you still need a serialization-safe tool. A plain SQL replace risks corrupting serialized values, so use Better Search Replace from the dashboard if you have no command-line access.
Why do my links still point to the old domain after a search-replace?
The most likely reasons are a second form of the old address, such as http instead of https or without www, a stale cache showing old pages, or URLs stored in a place the replace did not cover, such as a page builder or a theme file. Run the dry run again for each address form, clear plugin, server and browser caches, and check menus, widgets and builder data by hand.
Should I change the guid values to the new domain?
No. The guid is a permanent identifier for each post, mainly used by feed readers to tell whether they have shown an item before. WordPress docs say it must never change, even when the domain changes. Changing it makes feed readers treat old posts as new items. Always skip the guid column in WP-CLI with the skip-columns flag, and leave it alone in any plugin replace.
Do I need 301 redirects after fixing the links?
Yes, if the domain changed. Fixing links inside your own site does not help visitors who arrive from old bookmarks, other sites or search results. Each old URL should redirect to the same path on the new domain with a 301 redirect, which tells browsers and search engines the move is permanent. Keep the redirects in place after the move, and check a few old URLs by hand.
What should I do if the site breaks during the search-replace?
Stop and restore the database from the backup you made before the replace. Do not run more replaces on a half-changed database, because that makes the damage harder to trace. After the restore, check the search and replace strings for a typo, run a dry run again, and confirm the table prefix and the address forms. If the restore does not work, contact your host with the backup file ready.
Sources
- Migrating WordPress WordPress Developer Resources
- wp search-replace WordPress Developer Resources
- Better Search Replace WordPress.org
- How to Fix Your WordPress Site Not Working After a Migration Duplicator
- The Complete Post-Migration WordPress Testing Checklist (2026) Duplicator
- WordPress migrations BlogVault
- Use WP-CLI search-replace WordPress VIP Documentation
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
