Fixing "Error establishing a database connection" in WordPress

Instead of your site, you get one stark sentence: “Error establishing a database connection”. WordPress can’t reach its database, and without the database it has nothing to show.

The message itself points in a direction. In wp-includes/class-wpdb.php it says that either the username and password in wp-config.php are wrong, or that the database server at the given host could not be reached, possibly because it’s down. WordPress knows nothing more at that point. Your job is to find out what the message leaves open.

First: Which Error Is It Exactly?

Three screens look alike and have different causes:

• Front end and admin both show “Error establishing a database connection”. The connection fails. This is the main case of this article.
• The front end shows the error, the admin shows “One or more database tables are unavailable. The database may need to be repaired”. The connection works, but tables are damaged or missing. Jump to section 6. That note is set in is_blog_installed() (wp-includes/functions.php) and links to maint/repair.php.
• “Cannot select database”. The server accepted user and password, but the database named in DB_NAME couldn’t be selected. That’s its own message in class-wpdb.php. Password and host are fine then, usually the database name is wrong. On some systems the name carries a prefix, often your account name, and the message itself hints at that.

A completely blank white screen is something else again. The overview of WordPress errors covers that.

1. Are the Credentials in wp-config.php Correct?

The most common trigger, especially after a server or hosting migration. Open wp-config.php in the root directory and check these four values:

define( 'DB_NAME', 'database_name' );
define( 'DB_USER', 'user' );
define( 'DB_PASSWORD', 'password' );
define( 'DB_HOST', 'localhost' );

Typical mistakes: a typo in a name, a password that picked up a space or an altered special character when copied, or credentials of the old server that weren’t updated after the move. Don’t compare from memory. Compare against what the database section of your hosting panel shows.

DB_HOST: Port, Socket, localhost and 127.0.0.1

DB_HOST is often localhost, but with some hosts it’s a dedicated server name. WordPress accepts more than a plain name in this field: the parse_db_host() method in class-wpdb.php splits off a port (db.example.com:3306) and a socket path (everything from :/ on) and hands both to mysqli. IPv6 addresses are recognised too.

The difference between localhost and 127.0.0.1 matters. According to the MySQL documentation, on Unix a client connecting to localhost uses a socket file rather than TCP/IP, and any port option is then ignored. The PHP manual for mysqli says the same: with localhost the port is ignored, and if you need another port you use 127.0.0.1. So if your host gives you a port and localhost:3307 doesn’t work, that’s no coincidence. Only try switching if your host doesn’t tell you otherwise.

2. Test the Connection Independently of WordPress

A temporary test script tells you in a minute whether the credentials are right, including a plain-language explanation of the MySQL error:

Also available as a standalone page with all guides: connection test.

If you’d rather build it yourself, put a file dbtest.php in the root directory, enter the values from wp-config.php and open it in the browser:

<?php
mysqli_report( MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT );

try {
    $db = new mysqli( 'localhost', 'user', 'password', 'database_name' );
    echo 'Connected. Server version: ' . $db->server_info;
} catch ( mysqli_sql_exception $e ) {
    echo 'Error ' . $e->getCode() . ': ' . $e->getMessage();
}

Delete the file right after the test. It contains your database password in plain text.

With SSH access you can do the same on the command line with the MySQL client:

mysql -h localhost -u user -p database_name

If the login works, details and server are fine, and the problem lies in what WordPress does with them, for example because you’re checking a different wp-config.php than the one actually loaded. If it fails, the error usually points the way: “Access denied” means user or password don’t match, and a connection error to the host means the server isn’t reached.

3. Is the Database Server Even Running?

Check whether other sites on the same hosting are affected. If they are, the database server is the problem and all you can do is ask your host. A look at the hosting panel or the host’s status page often saves time.

On busy sites you may meet “Too many connections”. The MySQL documentation explains it: all permitted connections are in use by other clients. The limit is controlled by the max_connections variable. The server also allows one extra connection for accounts with the CONNECTION_ADMIN privilege (formerly SUPER), so administrators can investigate. On shared hosting you can’t change max_connections. You can only find out what is using the connections, such as a bot surge or a plugin with slow queries. On your own server you raise the value in the MySQL configuration, but you should first ask why so many connections are open.

A reached quota at your host happens too. The WordPress documentation on common errors explicitly lists a database that has met its quota and been shut down as a cause. The panel shows storage and database size, so you can see whether that applies. If a limit is full, free up space (old backups, log files, revisions) and ask your host to check the database service.

4. Reset Credentials with Your Host

If the database password has changed or the user is locked, reset both in the hosting panel and enter them in wp-config.php. Also check that the user is assigned to the database and has privileges on it. WordPress asks exactly that in its “Cannot select database” message. If you’re in the database anyway and still have login issues, Regain access to your WordPress admin takes it from there.

5. Error After a Migration or Host Change

If the error appears right after a move, work through this in order:

1. Was the database imported, and is it complete? In phpMyAdmin you can see the tables with the prefix from $table_prefix in wp-config.php.
2. Do DB_NAME, DB_USER and DB_PASSWORD match the new server? On a host change they almost always differ.
3. Is DB_HOST right? The new host may not use localhost.

siteurl and home are not the cause. Both values are options stored in the database itself, and WordPress can only read them once the connection works. A wrong domain after the move leads to redirects or broken styles, not to this message. If you changed domain and database at the same time, fix the connection first, then the URLs.

6. Is the Database Corrupted?

If the front end won’t load but the admin shows “One or more database tables are unavailable. The database may need to be repaired”, WordPress’s built-in repair often helps. According to the source, wp-admin/maint/repair.php runs REPAIR TABLE on the tables and can optionally run OPTIMIZE TABLE afterwards. Add to wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then visit https://www.domain.tld/wp-admin/maint/repair.php (with your own domain), start the repair and remove the line again afterwards. The page is reachable without a login while the constant is set, and WordPress itself tells you at the end to remove the line.

With SSH access and WP-CLI you can skip the browser. wp db check checks the tables, wp db repair repairs them. According to the WP-CLI documentation, both run the mysqlcheck utility with the credentials from wp-config.php:

wp db check
wp db repair

A repair is no substitute for a backup. Export what you still can before you start.

7. Has wp-config.php Been Tampered With?

If configuration and hosting look fine, the WordPress documentation lists a compromised site as the third possible cause. Warning signs are a modification date on wp-config.php you can’t explain, unknown users in the database, or foreign code in the file. Then restoring the connection isn’t enough, the cause has to go too. How to protect the configuration in future is covered in hardening wp-config.php.

When It’s Your Host and What to Send to Support

It isn’t on you if the test from section 2 fails with the values from the panel, if several sites on the hosting are affected, or if the error appeared without any change on your side. Send support:

• the exact error from the test script, not just “WordPress is down”
• when it first appeared and what changed before that
• the value of DB_HOST and the database name, without the password
• whether other sites on the same plan are affected

With that, support doesn’t have to ask follow-up questions.

Prevention

A current, tested backup turns this error into an inconvenience instead of a disaster. How to set that up sensibly is described in WordPress backups done right. Monitoring that checks the site from outside and tells you before visitors see the message fits alongside.

Quick Checklist

1. Classify the error: connection (front end and admin) or only a table notice in the admin.
2. Compare the credentials and DB_HOST in wp-config.php with the hosting panel.
3. Test the connection independently (mysqli script or mysql client), delete the script afterwards.
4. Check other sites, limits and “Too many connections”, then contact your host.
5. For a table notice: WP_ALLOW_REPAIR or wp db repair, remove the line afterwards.
6. After a move: import, user assignment, host.

An overview of other error patterns is in the overview of WordPress errors.

If the connection stays down, or you’d rather not touch credentials and the database yourself: drop us a line – we’ll restore the connection. With an ongoing maintenance plan, an outage like this shows up in monitoring before your visitors notice it.