The “Error establishing a database connection” message strikes fear in a WordPress users heart, prompting many a panicked support request. You try to load a page, but all you see is a white box with a mysterious error message. WordPress is down and the “helpful” suggestions beneath the error are more confusing than useful.
How can you fix a database error when you can’t even open the admin dashboard to see what’s wrong?
Fortunately, “Error Establishing a Database Connection” is straightforward to put right if you know what’s going on. Let’s take a look at WordPress’s relationship with its database, which is called MySQL®, what can go wrong, and, most importantly, what you can do to put WordPress and MySQL back on speaking terms.
Why Does WordPress Need a Database?
A WordPress site is composed of two parts: the files and the database.
When you download WordPress, there are static files and code files written in PHP, but you won’t find pages and posts, usernames and passwords, comments, or configuration data — that’s all stored in a MySQL database.
MySQL is a database server: it manages databases, tables, and the data stored in them. WordPress communicates with MySQL over the network, authenticating with a username and password before sending an SQL query that tells the database what to do.
For example, loading the WordPress home page executes a PHP file — usually the home.php or index.php file, depending on how the site is configured. The code connects to the database and retrieves the home page’s content, slotting it into a template that generates an HTML document.
What is a WordPress Database Connection Error?
A connection error is WordPress’s way of telling you that it can’t get the information it needs to build the page you’re trying to load. WordPress asked for data, and the database ignored it or said no. To fix the error, we have to figure out why MySQL is misbehaving.
There are several possible causes:
- Network connection errors — The database can’t be reached on the network. This might be because the database server is overloaded or the hosting provider has a network issue.
- Incorrect database credentials — WordPress is attempting to authenticate with credentials the database doesn’t recognize, so the request is denied.
- WordPress’s files are corrupted — Corrupt files can lead to invalid database requests or requests with the wrong credentials — a problem often caused by malware or a hacked WordPress installation.
- The database is corrupted — Corrupt databases are less likely than corrupt files, but editing the database manually and poorly coded plugins can cause database corruption. However, a corrupted database will usually show an error message such as “One or more databases are unavailable” instead of “Error Establishing a Database Connection.”
In summary, WordPress database errors usually mean WordPress can’t connect to or authenticate with the database or the database can’t respond with the right information.
How Do I Fix Database Connection Errors in WordPress?
It can be challenging to identify the error’s cause, so the best approach is to try the most likely fixes until your WordPress site starts working again.
Verify Database Credentials in cPanel
WordPress uses four pieces of information to talk to MySQL:
- 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. Open phpMyAdmin in cPanel and find the WordPress database in the left menu. Make sure the database name and the DB_NAME variable in wp-config.php match. Also, verify that the hostname matches the name in the database server section: it will almost certainly be “localhost.”
Next, check the “Users” section within the database entry to ensure that database’s username and password match the values WordPress is using. 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 check out but the error persists, it’s time to consider file or database corruption.
Repair the Database
Corrupt files are more likely, but minor database corruption is easier and less risky to fix so it’s worth trying first. There are a couple of ways to go about WordPress database repair. The first is to select phpMyAdmin in cPanel, navigate to your database, select all the tables, and 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
Choose the repair option and wait while WordPress does its thing. It might take a while but should handle 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 it triggered by malicious visitors.
Replace Corrupt WordPress Files
WordPress’s files can be corrupted by hardware problems, malware, or user errors. The goal here is to replace corrupt files with new ones freshly downloaded from WordPress.org while leaving your site’s plugins and themes in place.
Download a copy of WordPress, unzip it, and navigate to the “wordpress” directory. Delete the wp-content folder and the wp-config.php and wp-config-sample.php files.
Open the affected WordPress site’s root folder in cPanel File Manager and upload all the remaining files and folders from your local copy of WordPress. If cPanel asks whether to overwrite existing files, say yes.
All of WordPress’s core files will be replaced with pristine new files. 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 resolves the error, it is time to restore the WordPress site—both the files and the database—from a recent backup that was made before the connection error occurred.
It can be frightening when you first see “Error Establishing a Database Connection” on your WordPress site, but hopefully you now understand what the error means and the steps you can take to restore harmony between WordPress and its database.
If you have any further questions about fixing WordPress database errors with cPanel or wish to discuss anything cPanel related, please join us on our official Discord channel, our official cPanel subreddit, or our Support Forum.