The “error establishing a database connection” message is an especially frustrating WordPress error where your entire site gets replaced by a message that looks like this:
If you’re reading this post, there’s a good chance that you’re experiencing this error right now. If not, you are in luck.
And even if you’re not staring at this message, learning how to fix the error establishing a database connection problem is still something that every WordPress user should know.
In this post, you’ll learn three things:
- What the “error establishing a database connection” message means
- Some of the most common reasons why this message appears
- How to fix this error in WordPress
Page Contents
What Does The “Error Establishing A Database Connection” Actually Mean?
If you’re not familiar with how WordPress works, there are two essential parts to a WordPress website:
- Your files – this includes the WordPress software, your themes, your plugins, your media uploads, etc.
- Your database – this is where the actual content of your posts and pages are stored (as well as lots of other important information).
Whenever a visitor lands on your WordPress site, the PHP files in WordPress reach out to your database to determine exactly what information to display.
Without a working connection to the database, the PHP-file part of your WordPress site can’t get the information it needs to render a working page. That’s why it displays the “error establishing a database connection” message instead.
What Causes The “Error Establishing A Database Connection” Message?
There are multiple potential reasons why you’re seeing this message.
Most of the time, these causes boil down to:
- A corrupt database
- Incorrect database configuration details in your wp-config.php file
- Corrupt WordPress core files
- Problems with your web host
Because you can’t be sure what’s causing the message for your specific situation, the best way to fix the problem is to take a diagnostic approach.
That is, you need to systematically follow a series of tests to isolate (and then fix) the problem.
Here’s what to do:
How To Fix “Error Establishing A Database Connection” in WordPress
Potential Fix 1: Check If You Can Still Access The WordPress Dashboard
When you see this message on the front-end of your site, the first thing to do is check whether or not you get the same error when you try to access your wp-admin dashboard.
If you still see the same exact error message when you try to access your wp-admin area, skip ahead to the next step. You’ve already eliminated this problem as a potential cause.
If you see a different message mentioning something like “The database may need to be repaired”, continue with this section to learn how to repair your WordPress database.
Step 1: Turn on the repair utility in the wp-config.php file.
To get started, you need to edit the wp-config.php file for your site. You can do this by either:
- Connecting to your site via FTP. (FileZilla is a good program for that.)
- Using cPanel’s built-in File Manager tool.
Your wp-config.php file is located in the root folder of your WordPress site. That’s the same folder that contains wp-admin and wp-content:
Once you’re able to edit your wp-config.php file, add this short code snippet to the bottom of the file:
define( 'WP_ALLOW_REPAIR', true );
Make sure to save your changes before continuing.
Step 2: Run the automatic database repair utility.
Once you’ve added the code snippet, you can access the WordPress database repair tool by going to:
YOURDOMAIN.com/wp-admin/maint/repair.php
On that page, click Repair Database to run the tool:
Once the tool completes its repairs, your site should hopefully work again. If it does, all you need to do is return to your wp-config.php file and remove the same line of code that you added to enable the repair utility.
If your site still isn’t working, continue onto the next step.
Potential Fix 2: Check Your Database Login Credentials
If your database isn’t corrupt, the next thing you should check is whether your database login credentials are working.
Your database credentials are defined in your wp-config.php file:
If this information doesn’t match the database credentials that you created via your host’s dashboard, WordPress won’t be able to access your database.
To test whether your database credentials are working, you can use the mysql_connect() function.
Use a text editor like Notepad to create a file called databasecheck.php.
Then, add this code snippet to the file:
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
echo 'Connected successfully';
mysql_close($link);
?>
Make sure to replace “mysql_user” and “mysql_password” with the actual username and password from your wp-config.php file.
Then, upload that file to your website via the cPanel or by FTP and access it by going to:
YOURDOMAIN.com/databasecheck.php.
If you see a message that says “Connected successfully”, your database credentials are working and you can skip to the next step.
But if you see a message like the one below, you have a problem with your database credentials:
The easiest way to fix the problem is to create a new set of database credentials to use for your WordPress site.
Step 1: Go to MySQL Databases in cPanel.
Assuming your host uses cPanel, you can create a new database user by going to the MySQL Databases option in your cPanel dashboard:
Step 2: Create a new user.
Scroll down to the MySQL Users area and find the box to Add a New User.
Enter a new:
- Username
- Password
Make sure to remember these details as you’ll need them in a second.
Step 3: Add a new user to the database.
After you create a new user, go to the Add a User to a Database option and add the new user to your WordPress site’s database:
On the next screen, make sure to give the user ALL PRIVILEGES:
Step 4: Update the wp-config.php file with the new database user.
To finish, you need to go back to your site’s wp-config.php file and update the DB_USER and DB_PASSWORD fields to the new user:
Once you save your changes, your site should hopefully be working again!
Potential Fix 3: Reupload Core WordPress Files
If neither of the above methods fixed the error, some of your core WordPress files may be corrupt.
To ensure this isn’t the issue, you can upload a fresh copy of WordPress to your site. Done right, this won’t affect any of your existing content, plugins, or themes.
Go to WordPress.org and download the latest version of WordPress:
Then, extract the ZIP file and delete the wp-content folder and the wp-config-sample.php file:
Upload the remaining files to your WordPress site via FTP. When your FTP program asks you what to do about duplicate files, make sure to choose the option to Overwrite duplicate files.
This will ensure that none of your core WordPress files are corrupt, and it will hopefully fix the issue.
Potential Fix 4: Speak To Your Host
If none of the above solutions have worked, you may just be dealing with a hosting issue.
There are a couple of potential hosting problems:
- Your database server is down. Some hosts use a separate server for databases, which means your database might be down even if your regular server still works.
- Your database has met its quota. Some shared hosts put a cap on your database usage. If your site has met its quota, that might explain why your database is down.
To work through these problems, you’ll need to talk to your host’s support team.
Final Thoughts
By this point, you’ve hopefully been able to fix the error establishing a database connection message and have gotten your site working again.
There are still some smaller issues that might also cause this error. These issues are often unique to your site and are therefore hard to diagnose in a post like this.
If you continue seeing the error message after going through these fixes and talking to your host, you might want to consider reaching out to a WordPress developer to further investigate the issue.
Or, you can always leave a comment and hopefully we can all fix the problem together!