Home » Guides » Linux » Ubuntu WordPress Migration Troubleshooting
📌 Pin 🔗 Copy Link 📋 Copy Markdown ⬇️ Download
3 min read

Troubleshooting WordPress Migrations

Migrating a WordPress site rarely goes perfectly on the first try. Whether you used a plugin like UpdraftPlus or moved files manually, you might encounter errors. This guide covers the most common post-migration issues and how to fix them on an Ubuntu LAMP stack.

1. "Error establishing a database connection"

This is the most common error. It means WordPress cannot talk to the MySQL database.

Causes & Fixes:

  1. Incorrect Credentials:

    • Open wp-config.php: sudo nano /var/www/html/wp-config.php
    • Check DB_NAME, DB_USER, and DB_PASSWORD. Ensure they match the database and user you created on the new server.
    • Note: If you migrated wp-config.php from the old site, it still has the old site's password. Update it to the new server's database password.

  2. MySQL Server is Down:

    • Check status: sudo service mysql status
    • Restart it: sudo service mysql restart

  3. Localhost vs. IP:

    • In wp-config.php, DB_HOST is usually localhost. If your database is on a separate server, ensure this is the correct IP address.

2. 404 Errors on Posts and Pages

You can see the homepage, but clicking any link gives a "404 Not Found" error.

Cause:

The .htaccess file is missing or the permalink structure hasn't been updated.

Fix:

  1. Regenerate Permalinks:

    • Log in to wp-admin.
    • Go to Settings -> Permalinks.
    • Click Save Changes (you don't need to change anything). This forces WordPress to rewrite the .htaccess file.

  2. Check Apache Configuration:

    • Ensure mod_rewrite is enabled: sudo a2enmod rewrite
    • Check your Apache config (/etc/apache2/sites-available/000-default.conf) and ensure AllowOverride All is set for your web directory, allowing .htaccess files to work.

3. The "White Screen of Death" (WSOD)

The site loads a completely blank white page with no error message.

Cause:

A PHP error is suppressing output, usually caused by an incompatible plugin or theme.

Fix:

  1. Enable Debugging:

    • Edit wp-config.php.
    • Find define( 'WP_DEBUG', false ); and change it to true.
    • Reload the page. You should now see a specific PHP error message telling you which file is crashing the site.

  2. Disable Plugins Manually:

    • If you can't access the admin dashboard, rename the plugins folder:
    • sudo mv /var/www/html/wp-content/plugins /var/www/html/wp-content/plugins_old
    • If the site loads, one of the plugins was the culprit.

4. Permission Issues (Cannot Upload Images)

You can't upload media, install plugins, or update themes.

Cause:

The files are owned by your user account (e.g., ubuntu) instead of the web server (www-data).

Fix:

Reset ownership and permissions recursively.

sudo chown -R www-data:www-data /var/www/html
sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;

5. Site Redirects to the Old Domain

You migrated the site to a new domain (or staging IP), but it keeps redirecting you back to the old URL.

Cause:

The siteurl and home values in the database still point to the old location.

Fix:

  1. Hardcode in wp-config.php (Temporary Fix): Add these lines to wp-config.php:

    define('WP_HOME', 'http://your-new-domain.com');
define('WP_SITEURL', 'http://your-new-domain.com');

  2. Update Database (Permanent Fix):

    • Log in to MySQL: sudo mysql
    • USE wordpress;
    • UPDATE wp_options SET option_value = 'http://your-new-domain.com' WHERE option_name = 'siteurl';
    • UPDATE wp_options SET option_value = 'http://your-new-domain.com' WHERE option_name = 'home';

6. "Upload file exceeds the upload_max_filesize"

You try to upload your migration backup file, but it fails immediately.

Cause:

PHP has a default upload limit (usually 2MB), which is too small for backups.

Fix:

  1. Edit your PHP configuration (check your version, e.g., 8.1 or 8.3): sudo nano /etc/php/8.3/apache2/php.ini
  2. Find and increase these values:
    upload_max_filesize = 512M
post_max_size = 512M
memory_limit = 256M
  3. Restart Apache: sudo service apache2 restart
Created: March 17, 2026 • Last Modified: February 24, 2026