The message “Error establishing a database connection” causes panic in WordPress users, prompting many frantic support requests. When you try to load a page, all you see is a white box with an enigmatic error message. WordPress is unavailable, and the “helpful” suggestions beneath the error are more perplexing than helpful.
How can you troubleshoot a database error when you can’t even access the admin dashboard to see what’s wrong?
Fortunately, “Error Establishing a Database Connection” is simple to resolve if you understand what’s going on. Let’s look at WordPress’s relationship with its database, MySQL®, what can go wrong, and, most importantly, what you can do to get WordPress and MySQL talking terms again.
Table of Contents
Why Does WordPress Need a Database?
A WordPress site is made up of two parts: files and a database.
When you download WordPress, you’ll find static files and PHP code files, but no pages or posts, usernames, passwords, comments, or configuration data — all of that is stored in a MySQL database.
MySQL is a database server, which means it manages databases, tables, and the data contained within them. WordPress communicates with MySQL over the network, authenticating with a username and password before sending a SQL query that instructs the database.
Loading the WordPress home page, for example, executes a PHP file — typically the home.php or index.php file, depending on how the site is configured. The code connects to the database and retrieves the content of the home page, inserting it into a template that creates an HTML document.
What is a WordPress Database Connection Error?
A connection error is WordPress’s way of telling you that it is unable to obtain the information required to construct the page you are attempting to load. WordPress requested data, and the database either ignored it or said no. To correct the error, we must first determine why MySQL is acting strangely.
There are several possible explanations:
- Errors with network connections: The database cannot be reached over the network. This could be due to a database server overload or a network issue with the hosting provider.
- Incorrect database credentials: WordPress is attempting to authenticate with credentials that the database does not recognize, so the request is denied.
- WordPress’s files have become corrupted: Invalid database requests or requests with incorrect credentials can result from corrupt files, which are frequently caused by malware or a hacked WordPress installation.
- The database is corrupted: Corrupt databases are less likely than corrupt files, but manual database editing and poorly coded plugins can cause database corruption. A corrupted database, on the other hand, will typically display an error message such as “One or more databases are unavailable” rather than “Error Establishing a Database Connection.”
In summary, WordPress database errors usually indicate that WordPress is unable to connect to or authenticate with the database, or that the database is unable to respond with the correct information.
How Do I Fix Database Connection Errors in WordPress?
Because determining the cause of the error can be difficult, the best approach is to try the most likely fixes until your WordPress site resumes normal operation.
Verify Database Credentials in cPanel
WordPress communicates with MySQL using four pieces of information:
- The database name
- The database server’s hostname
- A username
- A password
They are stored as variables in the wp-config.php file in the WordPress installation’s root directory, and they look like this:
/** MySQL database username */
define(‘DB_USER’, ‘xxxxxx’);
The first step in verifying your database credentials is comparing the values listed in the wp-config.php file to those listed in the database. In cPanel, open phpMyAdmin and navigate to the WordPress database in the left menu. Make sure the database name and the DB NAME variable in wp-config.php match. Check that the hostname matches the name in the database server section, which will almost certainly be “localhost.”
Next, review the “Users” section of the database entry to ensure that the database’s username and password match the values used by WordPress. You can edit the values in the database to make them match those in wp-config.php or edit values in wp-config.php directly using the cPanel File Manager’s HTML Editor.
If the database credentials are correct but the error persists, file or database corruption is a possibility.
Repair the Database
Corrupt files are more likely, but minor database corruption is easier and less dangerous to repair, so it’s worth a shot first. There are two approaches to WordPress database repair. The first step is to navigate to your database, select all of the tables, and then click on the “repair table” item in the dropdown menu.
The second method takes advantage of WordPress’s built-in database repair mode, which you can activate by adding the following line to the wp-config.php file:
define(‘WP_ALLOW_REPAIR’, true);
Next, navigate to this URL:
https://yourdomain.com/wp-admin/maint/repair.php
Select the repair option and wait for WordPress to do its thing. It may take some time, but it should resolve the most common database corruption issues. Be sure to remove the line of code you added to wp-config.php when you have finished. Anyone can access the database repair URL, and you don’t want malicious visitors to use it.
Replace Corrupt WordPress Files
WordPress files can become corrupted due to hardware issues, malware, or user error. The goal here is to replace corrupt files with new ones that have been freshly downloaded from WordPress.org while keeping your site’s plugins and themes in place.
Download WordPress, unzip it, and go to the “wordpress” directory. Delete the wp-content folder and the wp-config.php and wp-config-sample.php files.
Open the root folder of the affected WordPress site in cPanel File Manager and upload all of the remaining files and folders from your local copy of WordPress. If cPanel prompts you to overwrite existing files, answer yes.
WordPress’s core files will be replaced with brand new ones. If this doesn’t resolve the database error, you may want to try replacing wp-config.php too, in which case you will have to edit the new version to add the correct database credentials, as discussed above.
If none of these methods work, it’s time to restore the WordPress site—both the files and the database—from a recent backup taken before the connection error occurred.
When you first see “Error Establishing a Database Connection” on your WordPress site, it can be frightening, but hopefully, you now understand what the error means and how to restore harmony between WordPress and its database.