Back to Community
Home / Community / Core → Localhost installs

Fixing Common Localhost WordPress Migration Issues: A Troubleshooting Guide

53 threads Sep 7, 2025 Core → Localhost installs

Content

Migrating a live WordPress site to a local development environment is a crucial task for developers, but it's often fraught with unexpected errors. Based on community reports, this guide covers the most frequent problems and their solutions when moving a site to XAMPP, MAMP, or Local by Flywheel.

Why Do These Localhost Migration Issues Happen?

The core of most migration problems lies in the fundamental differences between a live server and a local environment. Paths, server configurations, PHP versions, and database URLs are all hardcoded throughout a WordPress installation. When these values are not properly updated for the local setup, it leads to a cascade of errors, from broken styles and white screens to database connection failures.

Common Localhost Migration Problems and Solutions

1. PHP File Downloads Instead of Rendering

Symptoms: When you navigate to your local site URL (e.g., http://localhost/mysite), your browser prompts you to download a file (often index.php or download.php) instead of displaying the website.

Cause: This almost always indicates that PHP is not processing the .php files. The web server (Apache, Nginx) is treating them as plain text files to be served, not executed.

Solution:

  • Check PHP Processing: Ensure your local server stack (XAMPP, MAMP, etc.) is running correctly. Create a simple info.php file containing <?php phpinfo(); ?> and access it. If it also downloads, PHP is not configured.
  • Restart Services: Fully stop and restart your Apache and MySQL services through your stack's control panel.
  • Reinstall Stack: If the issue persists, a corruption in the server stack itself is likely. Consider reinstalling XAMPP or MAMP.

2. White Screen of Death (WSOD) or Blank Pages

Symptoms: You access your local site or the /wp-admin area and are greeted with a completely blank, white page.

Cause: A fatal PHP error is occurring, but error reporting is disabled, so nothing is displayed.

Solution: Enable WordPress debugging to reveal the underlying error.

  1. Open your local site's wp-config.php file.
  2. Find the line define( 'WP_DEBUG', false );.
  3. Replace it with these lines: 
    define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true ); // Logs errors to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // Hides errors from the screen
  4. Save the file and refresh the page. The error will now be written to wp-content/debug.log. Check this log file for the specific error message, which will point you to the problematic theme, plugin, or configuration.

3. Broken Permalinks and 404 Errors

Symptoms: The homepage loads, but clicking on any post or page link results in a 404 "Not Found" error. The admin login page (/wp-login.php) might also return a 404.

Cause: Apache's mod_rewrite module is disabled, or the .htaccess file is missing/not being read.

Solution:

  • Enable mod_rewrite: In XAMPP, open httpd.conf and ensure the line LoadModule rewrite_module modules/mod_rewrite.so is uncommented (does not have a # at the start).
  • Allow .htaccess Overrides: In your Apache configuration, find the <Directory> block for your web root (e.g., /opt/lampp/htdocs) and change AllowOverride None to AllowOverride All.
  • Restart Apache after making these changes.
  • Refresh Permalinks: Log into your WordPress dashboard (you may need to use "Plain" permalinks temporarily), go to Settings > Permalinks, and simply click "Save Changes" to regenerate the .htaccess rules.

4. Missing Styles, Scripts, and Formatting

Symptoms: The site loads but looks completely unstyled, like a plain text document. The browser's console shows 404 errors for .css and .js files.

Cause: The site URL or home URL in the database is still pointing to the old live domain, so the browser is trying to fetch assets from a server that doesn't exist locally.

Solution: Perform a complete search-and-replace on the database for the old URLs.

  1. Use a Tool: The safest method is to use a dedicated script like Interconnect IT's Search and Replace script. Upload it to your local site root, run it via the browser, and replace all instances of http://my-live-site.com with http://localhost/my-local-site.
  2. Manual SQL Query (Advanced): In phpMyAdmin, you can run an SQL query on the wp_options table (note: table prefix may vary): 
    UPDATE wp_options SET option_value = replace(option_value, 'http://old-url.com', 'http://localhost/new-url') WHERE option_name = 'home' OR option_name = 'siteurl';
    Warning: Manually editing the database can break serialized data if not done carefully. Always back up first and prefer the dedicated script.

5. Database Connection and "Error Establishing a Database Connection"

Symptoms: WordPress cannot connect to the database on your local server.

Cause: Incorrect credentials in the wp-config.php file.

Solution: Double-check the database connection details in your local wp-config.php file.

  • Database Name: The name of the database you created in phpMyAdmin.
  • Username: For XAMPP/MAMP, this is often root.
  • Password: For XAMPP/MAMP, this is often blank (an empty string '').
  • Host: This should be localhost.

General Best Practices for a Smooth Migration

  • Use a Migration Plugin: Plugins like Duplicator or All-in-One WP Migration can automate much of the database search-and-replace process, though they can sometimes fail with very large sites.
  • Match PHP Versions: If your live site runs on an older PHP version (e.g., 5.6), try to match that version locally to avoid compatibility errors with old themes/plugins. Tools like Local by Flywheel make switching PHP versions easy.
  • Check Server Logs: When all else fails, your local server's error logs are your best friend. Check the Apache error log (often in a logs/ directory within XAMPP/MAMP) for detailed error messages that can pinpoint the exact issue.

Migrating a WordPress site to localhost can be complex, but methodically working through these common issues will usually lead to a successful setup. The key is to enable debugging, check logs, and ensure your local server configuration matches WordPress's requirements.

Related Support Threads Support