If WordPress is throwing up a message telling you “Error establishing database connection” on an otherwise blank page, it means your database cannot be reached. And, obviously, your site it down. But you probably already figured that.
In most cases, this error appears because the credentials you entered for your database aren’t correct, you made a mistake installing or migrating your site, or your database tables are corrupted. In any case, you’ll be happy to know it’s usually one of the simpler WordPress errors to resolve.
Read on to find out more about this error, how it happens and how to fix it. I recommend starting at the top of the list of solutions and working your way down until your site is back up.
What Is This Error and How Does It Happen?
Your site can be seen as having two main parts to it: Your files and your database. Your MySQL database stores much of the data that displays on your site such as usernames, passwords, posts, categories, tags and other content.
Your PHP files are built to request this information from your database and your database sends this information along to your files. Both sets of information are then put together so your site can be displayed when a browser asks for the page to load.
If something’s wrong with your database, your PHP files can request information from your database, but when your database doesn’t respond back by serving up the requested data, you’re left with the error:
“Error establishing a database connection.”
Your PHP files are unable to connect to your database and there could be many reasons for it. Since this is the case, the trickiest part of fixing this error is figuring out exactly what caused it.
Beyond not being able to connect to your database, here are more specific reasons behind what may have caused this error:
- You may have made an error installing WordPress or migrating it
- The database may have been deleted by accident
- You could have the wrong credentials entered
- There’s a conflict with the database prefix
- Your file permissions could be set incorrectly
- Your site URL may not be correct
- You may have plugins or themes installed that are causing the issue
- Your files or database may be corrupted
- There could be a malfunction with your server or it’s overloaded
Sometimes the error could come up after making some changes to your site that seem innocent enough until they take everything down. That’s why it may be helpful to mention that testing changes before you publish them could help you avoid this situation in the future.
You can check out some of our other posts for details on how to test changes before pushing them live:
If you’re reading this, chances are you are experiencing this error right now and you’re keen to try the fixes below right away. Start with the first one and work your way down the list since it starts with the most common solutions and progresses to the more complex issues and fixes.
Before You Get Started: Back up and Restore!
Before you make any changes to your site to try and fix this error, it’s a good idea to back up your entire site as-is just in case. It’s better to have a backup of a slightly broken site than nothing at all. If things get worse, you can at least go back to where you started.
You can check out How to Manually Backup Your WordPress Website for details on how you can backup your site in this situation.
If you already have a backup of a restore point when your site was working, go ahead and restore your site.
This may not be the best solution for everyone, especially if your users have submitted a lot of content in your Multisite network that you don’t want to lose. If this is the case for you or you don’t have a valid backup of your site, you can try some of the other fixes below.
1. Deactivate Your Plugins
Sometimes, a plugin could make a change to your database that ends up breaking your site, such as if you have a security plugin that changes your database prefix or file permissions, for example. If your other plugins don’t expect this to happen, it could cause a malfunction and your site would go down.
Also, some managed hosting plans have a strict list of plugins you aren’t allowed to install and activate to ensure the security of the server you’re renting from them. If you were to install and activate the prohibited plugin, it could bring down your site.
That’s why deactivating your plugins can often be an effective way to troubleshoot and fix the connection error at the same time. Since you don’t have access to your backend to deactivate your plugins, this is still possible by accessing your files.
After logging into cPanel, go to Files > File Manager and find the directory your site is in. Navigate to /wp-content/plugins/ and for each of the plugin folders listed, temporarily rename them.
Click on the first one on the list, then select the Rename button at the top of the page.
Keep the original name intact so you don’t forget what the plugin was later on, but add something at the end such as
-deactivated to remind you why you renamed it.
Click Rename File and move on to renaming the other plugins on the list in the same way. If your site comes back up, then that means one of your plugins was responsible.
Rename the plugin folders to their original names one-by-one and check if your site is available between each name change. When your site goes back down, the culprit is the last plugin you reverted to its original name.
At this point, you can look into the plugin more in-depth to find out exactly what the cause was for the error and you can also replace it with a similar plugin.
It’s important to note that if one of your plugins made a major change to your database that caused your site to go down, deactivating the plugin won’t fix the problem. In such a case, you would need to continue through the fixes below to resolve the issue.
2. Checking Your Credentials
Verifying Your Site’s URLs
If you haven’t been able to get your site back up yet, check the details you have written in your wp-config.php file and compare them to the information for your database. Fortunately, you don’t need to be able to access the backend of your site.
In cPanel, you can find your wp-config.php file by going to Files > File Manager and navigating to the directory where your site is located. Click on the wp-config.php file on the list, then click Edit at the top of the page.
There are a few things you need to look for and you should also make a note of them so you can compare what you find here with what should be the same details in your database.
First, take a look through the wp-config.php file and see if you can find something similar to the example below:
You may not see these two lines because you need to add them in yourself, but if you added them previously, then you need to make note of them and make sure they’re correct. If they’re not, correct them right away.
To correct the URLs, substitute
http://your-site.com in the example above for the correct URLs of your site. Also, be sure it’s properly structured and doesn’t have any typos. If you have an SSL certificate enabled on your domain, you should replace
You also need to pay close attention to whether the URLs that you found have
www. included. If your database includes a URL without it or vice versa, then this needs to be changed to match your database.
You can also see more details on SSL certificates by checking out one of our other posts How to Use SSL and HTTPS with WordPress.
You can also try adding these two lines with the correct URLs if they’re not already there. Sometimes the database may become unavailable because the incorrect URLs were entered into the Settings > General page in the admin dashboard for single installs of WordPress or before Multisite was enabled.
If you add these lines and the error persists, you can take them out and continue trying the next fixes. You could also try a similar approach with the functions.php file found under the /wp-includes/ folder.
See if you can find similar lines to these examples below:
Just like the example above for the wp-config.php file, these lines are only in your functions.php file if you added them before. If you do see them, make sure they’re correct and free of typos and if not, correct them, then see if your site goes back up.
http://your-site.com for your actual URLs and if you have an SSL certificate installed, don’t forget to add
https:// instead of
Also, check if
www. is included in the URLs since if it’s not included in the database but it’s present in your file and vice versa, then your site would go down. Make the change to include or remove
www. from the URL if necessary.
If your site comes back up or if it doesn’t remove the lines above and don’t leave them there. If that didn’t work, continue with the other fixes.
Checking Your Database Details
Go back to your wp-config.php file and look for this block of text that you can find toward the top of the document:
Make a note of your database name, username, password and hostname. In the example above, your database name would be where you see
database_name_here, your real username would replace
username_here and your actual password would be found where the example displays
Chances are your hostname would be the same and would be
localhost, although, it may be different for you. It’s important that you contact your hosting provider and verify whether this line is correct and if
localhost should be set to something else instead.
If a change needs to be made to your hostname, save it to your wp-config.php file and check if your site is up.
If your host verifies that your hostname is correct or the change you made doesn’t do the trick, then make a note of all the other credentials in the example above and scroll down slightly in the document.
Also, look for a similar line to the one below to find the database prefix that your files are requesting:
You may have something different in your file than
wp in the example above, but whatever the value is before the underscore, this is what should also be found in your database. Make a note of this as well.
Next, go back to the cPanel homepage and click on the MySQL Databases button under the Databases section. Scroll down to the Current Databases section and find the database for your site on the list.
Compare the database name and username listed here with this same information listed in your wp-config.php file. If the details don’t match, change these details in your wp-config.php file so they’re the same. Don’t forget to save your changes.
You would change the login credentials that were previously mentioned above in the
define('DB_NAME', 'database_name_here'); and
define('DB_USER', 'username_here'); lines. You would change the
database_name_here part for the actual database name you looked up and the
username_ here portion for the correct username you found.
You can also try updating the password associated with the username for your database. On the MySQL Databases page, go to the Current Users section and click the Change Password button.
Once you have changed the password, update your wp-config.php file to reflect the change. You would update the
define('DB_PASSWORD', 'password_here'); line and in particular, the
Check if your site is up and if not, you can verify that your database username and password is correct and that this user can successfully connect to your database.
Create a test file in the root of your site and save the following code to it to make sure there’s no room for human error:
Don’t forget to change
your_hostname with your correct hostname,
databse_username with your actual database’s username and finally, replace
database_password with your real password.
You can name the file anything you want, but I recommend something that’s descriptive such as testdatabase.php or testdb.php. Just be sure it ends in .php or this test won’t work.
Once that’s done, access this file from your browser. Using the example above, you would go to http://your-site.com/testdb.php and if the login details work, you would see a “success” message on the page.
If the connection to your database is unsuccessful, then you know either your username or password isn’t matching up and needs to be changed in your wp-config.php file. You can review the steps above to make the changes.
You can also try creating a new username and password if all else fails. In cPanel, go to Databases > MySQL Databases and scroll down to the Add New User section.
Enter a new username and password and click the Create User button. Now you can add this new user to your database.
The next area on the page lets you add a the new user you created to your database. Select it from the drop down list labelled User.
Next, select your database from the list right under it. Click the Add button and your new username is added to your database.
The final step required is to update your wp-config.php file to reflect these new login details. You would do it in the same was that was previously outlined, but be sure to include the database prefix when adding it to your wp-config.php file or else it won’t work.
Don’t forget to save your file changes. Now, you can visit your site and see if it’s back up. If it’s still a no-go, you can try repairing your database.
3. Fixing Your Database
Restoring Proper Permissions
When all else fails, you can try checking your file permissions to make sure they’re set correctly. If they’re not set properly, it can cause the database connection error.
You can check out our post Understanding File Permissions and Using Them to Secure Your Site for details on how to properly set file permissions, although, there’s an easier way to reset the permissions for your files.
You can replace all your core files with fresh ones. To do this, download the latest copy of WordPress from WordPress.org. Uncompress the folder and delete the wp-config-sample.php file and /wp-content/ folder.
Since both of these contain crucial data you need for your site to work, you don’t want them replaced at all costs. Deleting these from the fresh copy eliminates accidentally overwriting them on your site.
Use your favorite FTP client to transfer the fresh copies of the WordPress core over to your site and don’t forget to choose the option to overwrite all the old files with the new. That way, you won’t have to worry about the added step of deleting your old files before you transfer over the new ones.
For details on using FTP, check out our post How to Use FTP Properly with WordPress.
Repairing Your Database
Repairing your database tables usually works if everything else you have tried doesn’t seem to do the trick, especially if you have access to your front end or back end, but not both.
To repair your database, open your wp-config.php file in cPanel or after downloading it through FTP and add the following line to it, then save the file.
Unlike most other edits to this file, it doesn’t exactly matter where you place it as long as it’s not smack-dab in the middle of another line. You can place it before the “happy blogging” line like you would other additions so you don’t forget about it or right at the end. Whatever works for you is fine.
Once it’s saved, go to your site with the following URL structure:
Don’t forget to replace
your-site.com with your actual domain. When you reach the page, click the Repair Database button.
Once the repair has completed, immediately remove the line you added to your wp-config.php file to enable the database repair. It’s not an option you want to keep enabled to ensure a hacker doesn’t take advantage of it to infiltrate your site.
You can now visit your site and check whether it has come back up. If not, there’s one final hail Mary pass.
4. Contact Your Host
If you have tried everything and nothing seems to work, contact your hosting provider since they may be aware of issues on your server that have nothing to do with anything you did, but still causes your site to display the connection error.
Let them know what you have already tried and even link them to this post for an easier time explaining the steps you took.
Other than that, your site should be back up and running again and the “error establishing database connection” issue should be history.
Still, it doesn’t hurt to keep regular backups of your site so you can easily restore your site if something goes wrong in the future and Snapshot Pro can help you keep on top of your backups.
Have you experienced the error establishing database connection on your site? What did you do to resolve it? What are your favorite tools and tips for resolving this error? Share your experience in the comments below.