---
tags:
  - wordpress
  - troubleshooting
  - migration
  - database
  - ubuntu
  - lamp
---

# 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.

```bash
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`:
    ```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:
    ```ini
    upload_max_filesize = 512M
    post_max_size = 512M
    memory_limit = 256M
    ```
3.  Restart Apache: `sudo service apache2 restart`