WordPress Site Broken After Migration

Why migrations break WordPress

A WordPress site is not just files, it is files plus a database, and the two have to agree about where the site lives and how to reach the database. A migration moves both to a new place, and breakage happens wherever something still refers to the old place. The files carry the code, but the database carries the site address, every internal link and image path saved in your content, the widget and theme settings, and the connection details WordPress uses. Move the site without updating those references and WordPress keeps trying to behave as if it were still on the old host at the old domain.

That is why the same handful of problems show up after almost every migration. The database still contains the old URLs, so links and assets point at the old domain. The wp-config.php file still has the old database credentials, so WordPress cannot connect to the new database. The stored WordPress Address and Site Address still name the old domain, so the admin redirects you away. The rewrite rules that power permalinks did not come across, so inner pages 404. And if the move also switched to https, the old http URLs in the content trigger mixed-content warnings. None of these is mysterious once you see the pattern: the new home, the old references.

The one genuine subtlety, and the thing that turns a routine migration into a mess, is how those old URLs get updated. Because WordPress stores many settings as serialized data, you cannot simply find-and-replace the old domain in a database dump or with a SQL query. Do that and you corrupt the settings. The correct fix is a tool that understands the serialized format, and getting that one detail right is most of the difference between a clean migration and a broken one.

First, make sure it is really broken

Before you change a single file, rule out the most common false alarm, because a large share of post-migration panics are not broken sites at all. When you point a domain at a new host, the change does not take effect everywhere at once. DNS, the system that maps your domain to a server, propagates gradually, and during that window some visitors, and possibly you, still reach the old server. On top of that, your browser cache, a caching plugin, and any CDN can keep serving the old version well after DNS has updated. So the broken or unchanged site in front of you may be the old server, not the migration you just finished.

Which symptom matches yours

Find the row that matches what you see. Each one points to a specific cause and fix.

The six root causes

Once you have confirmed you are on the new server, post-migration breakage is almost always one of these six.

The serialized-data trap

This is the detail that separates a clean migration from a broken one, and it is worth understanding even if you never touch the database yourself. WordPress stores a lot of settings as serialized data, a text format that packs an array or object into a single string. The catch is that the format records the exact character length of every value. A piece of serialized data that contains https://oldsite.com also stores the number 19, the length of that string, right next to it.

Now do a blind find-and-replace, swapping https://oldsite.com for https://my-new-domain.com. The text changes, but the stored length still says 19 when the new value is longer. WordPress reads the length, expects 19 characters, finds a different number, and decides the whole serialized string is invalid. It does not error loudly. It quietly discards that setting and uses the default. That is why a raw SQL replace or a hand-edited database export so often comes out the other side with reset widgets, blank theme options, and lost plugin configuration, while the URLs in your posts look fine.

DIY vs hand it off

A single clear cause with access to the files and database is a reasonable self-fix. A corrupted database, a lockout, or several issues at once is where handing it off saves time. If the left column matches you can likely do this. If the right column matches, get help.

How to diagnose it

Work in this order. The first step prevents the most common wasted hour.

How to fix it

Each branch stands alone. Pick the one your diagnosis pointed to. Back up the database before any search-replace.

define( 'DB_NAME', 'new_database_name' );
define( 'DB_USER', 'new_database_user' );
define( 'DB_PASSWORD', 'new_database_password' );
define( 'DB_HOST', 'new_database_host' ); // often NOT localhost

# Preview the change without writing anything
wp search-replace 'https://oldsite.com' 'https://newsite.com' --all-tables --dry-run

# Run it for real, skipping the guid column that should stay stable
wp search-replace 'https://oldsite.com' 'https://newsite.com' --all-tables --skip-columns=guid

define( 'WP_HOME', 'https://newsite.com' );
define( 'WP_SITEURL', 'https://newsite.com' );

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

A real migration-recovery session

A composite from the migration repairs we run most weeks, with identifying details removed.

WordPress migration FAQ

Sources and further reading

Every technical claim on this page traces back to the WP-CLI documentation, the WordPress documentation, or the named plugin and host references.

• WP-CLI: search-replace command (serialization-safe URL replacement)
• WordPress: Better Search Replace plugin
• WordPress: Changing the site URL
• WordPress: Moving WordPress to a new server or host
• WP Engine: Managing serialized data in WordPress