Seeing this error on a live site usually points to a hosting-side problem, and WordPress.org’s own developer documentation on common errors covers those cases well. On localhost, the causes are almost always different, since you’re the one running the database server yourself. A guide written for production sites won’t help much here, because things like “contact your host” simply don’t apply when the database is sitting on your own machine.
Here’s how to work through it specifically for a XAMPP or MAMP local install.
Step 1: Confirm MySQL Is Actually Running
This is the most common cause, and the easiest to miss. Open your XAMPP or MAMP control panel and check the status next to MySQL.
- XAMPP: the MySQL row should show a green “Running” status. If it’s not running, click Start next to it.
- MAMP: both Apache and MySQL indicators at the top of the MAMP window should be green.
If MySQL won’t start at all, check the XAMPP or MAMP log for a specific error – a common cause is another program already using the same port (more on that in Step 4).
Step 2: Check wp-config.php Against Your Actual Local Credentials
Open wp-config.php in your WordPress install folder and confirm these four lines match what you actually set up in phpMyAdmin:
define( 'DB_NAME', 'your_database_name' );
define( 'DB_USER', 'your_database_user' );
define( 'DB_PASSWORD', 'your_database_password' );
define( 'DB_HOST', 'localhost' );
A frequent mistake here: XAMPP’s default MySQL user is root with a blank password, but MAMP’s default is often root / root for both username and password. Copying a wp-config.php from a live site, or from a XAMPP setup onto a MAMP one, will bring the wrong credentials with it.
Also double check DB_NAME matches the exact database name shown in phpMyAdmin – a typo here, or forgetting to actually create the database before installing WordPress, will trigger this exact error.
Step 3: Check the DB_HOST Value, Including the Port
localhost on its own works for the outside majority of setups, but not always. If XAMPP’s MySQL is running on a non-default port, or if you’re using MAMP, you may need to include the port number directly in DB_HOST:
define( 'DB_HOST', 'localhost:3307' ); // Example port
For MAMP specifically: MAMP typically runs MySQL on port 8889, not the standard 3306. Check MAMP’s preferences panel under the “Ports” tab to confirm the exact port your installation is using, and update DB_HOST to match.
Step 4: Watch for Port Conflicts
MySQL’s default port, 3306, is sometimes already claimed by another program on your computer – a previous MySQL install, certain VPN software, or in some documented cases, older versions of Skype. When that happens, XAMPP often shifts MySQL to port 3307 automatically, without clearly telling you.
To check which port XAMPP’s MySQL is actually using, open the XAMPP Control Panel, click “Config” next to the MySQL row, and open my.ini. Look for the port line under [mysqld]. Whatever number is there needs to match what’s in your DB_HOST line from Step 3.
Step 5: Mac Users – Check the Socket Path (MAMP)
On Mac, MAMP sometimes needs a socket path rather than a standard host:port combination, especially if a plugin or migration script hardcoded a socket location from a different setup. If Steps 1 through 4 haven’t resolved it and you’re on MAMP, try:
define( 'DB_HOST', 'localhost:/Applications/MAMP/tmp/mysql/mysql.sock' );
Adjust the path if your MAMP installation isn’t in the default Applications folder.
Step 6: Repair the Database Tables
If the connection itself is fine but you’re still seeing the error, one or more database tables may have become corrupted – this can happen after an interrupted import or a forced computer shutdown while MySQL was mid-write. Add this line temporarily to wp-config.php, just above the line that says /* That's all, stop editing! */:
define( 'WP_ALLOW_REPAIR', true );
Then remove the line once you’ve confirmed the repair worked, since leaving this page publicly accessible is a real security risk on a live site (though less of a concern on localhost specifically).
If you’re troubleshooting other local development errors beyond this one, we’ve also covered a related connectivity issue in our DNS_PROBE_FINISHED_NXDOMAIN error guide – worth checking if your local site won’t even load in the browser before you get to a database error at all.
FAQ
Why does this same wp-config.php work on my live site but not on localhost?
Because the two environments almost never share the same database credentials, host value, or port. A wp-config.php copied directly from production will need these details changed to match your local MySQL setup.
I just installed XAMPP for the first time and got this error immediately. What’s wrong?
Check that you actually created a database in phpMyAdmin before running the WordPress installer. WordPress can’t establish a connection to a database that doesn’t exist yet – a step that’s easy to skip since some tutorials assume it’s already done.
Does this guide apply to Local by Flywheel or DevKinsta too?
Not directly. Those tools manage the database connection automatically behind the scenes, so this specific error is rare with them, and when it does happen the cause is usually different (like a corrupted local site environment) rather than the port or credential issues covered here.
