© Nead, LLC

Menu Close
Close

How to Troubleshoot the Error Establishing a Database Connection in WordPress

Did you try to load a page on your WordPress website and get a message that reads: “Error establishing a database connection” on your screen? Like all other WordPress error messages, this is an inconvenience and makes your site inaccessible to your visitors. However, there’s usually an easy solution.

As indicated by the error, the problem is that your WordPress installation can’t connect to your database. This can happen for a variety of reasons, under several common circumstances, but if you aren’t familiar with databases, it can be challenging to troubleshoot.

In this article, we’ll explain how this error happens and what you can do to fix the problem.

Understanding your database

Understanding your database

First, it’s important to understand what a database is and how it works. In a nutshell, a database holds information so that an application can access and display that information on web pages. For example, your WordPress database holds all of your posts, pages, and comments. In order to display this content, WordPress has to communicate with the database and connect to it using a password.

A successful database connection allows WordPress to display the content it’s requesting on your website. If you load your website and get the database connection error message, it means something has gone wrong with WordPress’ attempt to access your database.

How WordPress connects to your database

Each time a user loads a page from your website, WordPress accesses the database to display the page. The following information is stored in your wp-config.php file, which is used to access the database:

  • Database server
  • Database name
  • Database username
  • Password for the database user

All of the above information must be correct in order to establish a connection with the database. Incorrect data will return the “Error establishing a database connection” error.

1. Your credentials are incorrect

Having incorrect credentials in your wp-config php file is the most common reason for getting this error. Usually, this happens when you’re implementing a fresh installation of WordPress and you’ve mistyped your credentials.

Hopefully, you documented the name of your database, database user, and password when you created these details. If you don’t know your database user’s password, you’ll need to change the WordPress database credentials and make sure to document it in a file.

To check on your credentials, navigate to your file manager or open your website using an FTP application. Find your wp-config.php file (it should be in your root directory) and open the file in your editor or text application. Look for the following chunk of content:

1. // ** MySQL settings - You can get this info from your web host ** //

2. /** The name of the database for WordPress */

3. define( 'DB_NAME', 'database_name_here' );

4. /** MySQL database username */

5. define( 'DB_USER', 'username_here' );

6. /** MySQL database password */

7. define( 'DB_PASSWORD', 'password_here' );

8. /** MySQL hostname */

9. define( 'DB_HOST', 'localhost' );

The text ‘database_name_here’ should show your database name. If you’re using cPanel, your database name will begin with a prefix of your account username followed by an underscore followed by your chosen database name.

The text ‘username_here’ should be the database user you assigned to your database with full admin privileges.

Finally, the text ‘password_here’ should be your database user’s password.

If all of your credentials appear correct, and you’re trying to create a fresh install, you may have mistyped your information on the installation screen. Another possibility is that your database host information might be incorrect. Usually, it’s going to be ‘localhost’ but your web host might use a different server for databases. Open a ticket or a chat request to verify with your host that ‘localhost’ is correct. If not, they’ll tell you what to use instead.

If these things are not the issue, try some of the other possibilities in this article.

2. You never added the user to your database

Error establishing a database connection

Another common reason for the “Error establishing a database connection” is that your user hasn’t been added to the database. This wouldn’t apply if your site was working and suddenly stopped. However, with a new installation of WordPress, this is common.

Once you create your database, you have to create a database user. Then, you have to add that user to the database you just created and assign that user all administrative privileges. If you don’t add the user, you won’t make a connection. Likewise, if the user doesn’t have full administrative privileges, your database connection will fail.

To troubleshoot this potential, navigate to the section for databases in your hosting account’s back end. Retrieve a list of your databases to see which users have been assigned to each database. Check to make sure you’ve assigned the correct user to your intended database. If that’s not the case, there will be a form that will allow you to add the user to your database.

3. You moved your WordPress installation

Moving a WordPress installation can sometimes create the “Error establishing a database connection.” This usually happens when you move your installation to another directory or domain name, and something goes awry in the process.

This is a slightly more complicated fix, but here’s a guide from CSS Tricks that explains how to move your WordPress installation and change options, like your siteurl and home URL directly in the database.

4. Your server is down

Web servers go down from time to time. Sometimes it’s planned, sometimes not. Spikes in traffic can cause servers to go down, but so can hackers and system reboots. Either way, a down server commonly causes the “Error establishing a database connection” message.

If the error persists for long, contact your webhost to find out if your server is down. It might be in the process of being rebooted, and if so, the issue shouldn’t persist for long.

5. Some database files are corrupt

It’s possible for files in your database to be corrupt, either by accident or due to hackers. When you’re constantly installing plugins, editing themes, and adding content to a database, it’s more prone to data becoming corrupt.

You can fix a corrupt database by using a built-in WordPress feature for database repair. To enable repair mode, you’ll need to add the following line of code to the end of your wp-config.php file:

define(‘WP_ALLOW_REPAIR’, true);

Then, navigate to the following URL on your domain name:

https://yourdomain.com/wp-admin/maint/repair.php

On the screen, you’ll be able to repair your database or optimize and repair your database. Optimizing your database can take a long time, so if you want to fix your site fast just stick with the repair only option.

7 not-so-common reasons for this error

Once you troubleshoot the most common reasons for this error, if nothing works, there are several more options you can try before calling a programmer.

1. Your user was removed from the database

If your site used to work, but no longer connects, it’s possible that your user was removed from the database. If you have other people who work on the site and access your control panel, they might have accidentally deleted your user from your WordPress database.

This is easy to verify by logging into your hosting account and finding the section for databases. Find your WordPress database in the list and make sure your user is still assigned with full admin privileges. If not, reassign the user with administrative rights.

2. Your database user privileges were downgraded

This potential isn’t common, but if multiple people are accessing your control panel, you never know what they might be experimenting with on the back end. For example, say someone accidentally deletes your user from the database, then adds that user back to fix the problem. Unbeknownst to them, they might not have given that user full admin privileges.

It won’t hurt to remove the user from the database and then re-add them with full administrative privileges just to be sure.

3. Your database user was deleted

If you have people clicking around in your control panel who don’t know what they’re doing, it’s possible that someone may have deleted your database user. This usually happens when someone is trying to clean up unused databases and users and doesn’t realize they’ve deleted the wrong data.

4. Your database was renamed

If anyone renames your database, WordPress won’t be able to connect anymore until you update your wp-config.php file with the new database name.

There’s almost never a good reason to rename a database, so this possibility would be more of a mistake than something intentional. However, the problem could also be that you chose a different prefix for your database tables and you’re trying to access your database with the wrong prefix.

The standard prefix is ‘wp’, but many people change this for security purposes. If you’re trying to install WordPress and can’t connect to the database, check to make sure you’re using the correct database table prefix during the installation process.

5. Your wp-config.php file was moved or deleted

wp-config.php file

WordPress relies on this file to connect to the database. If it can’t be found, you won’t get a connection. Log into your file manager or FTP application to make sure the file is in your main directory. If not, try to locate the file or create a new one.

6. There’s a typo in your wp-config.php file

PHP files are particular about typos. If you have a comma, semicolon, bracket, or parenthesis out of place, it will be as though that file doesn’t even exist. WordPress will attempt to access your wp-config.php file but won’t get anywhere.

Check your configuration file for typos, and if you can’t find any obvious errors then just get a fresh file and start from scratch. Don’t waste your time trying to find a typo if you aren’t sure one exists; it could drive you crazy for hours. Just start fresh, add any custom code you had in your previous version (checking each line for errors), and re-enter your database information. This will effortlessly override any typos that may have been there.

7. You copied and pasted your MySQL database password from a Word document

Microsoft Word loves autocorrect, and sometimes if you paste a password into a Word document, the application will attempt to automatically correct parts of that password if it seems like it should be a different word. It’s very possible that you may have pasted your password into Word without noticing the autocorrect being applied to it after you hit the space or enter key.

If you’re stuck on this error, but you have yet to try changing your database user’s database login credentials, try that now. Then, instead of storing your password in Microsoft Word, use a plain text editor.

Still can’t fix the “Error establishing a database connection” message? We can help!

Troubleshooting an error message in WordPress can be simple, or it can be complex. The problem is you can’t know ahead of time. If you’ve been trying to fix this problem by yourself, but you aren’t getting anywhere, contact us for help.

At Website.Design, we are WordPress design and development experts and can help you with anything you need. We can fix errors, upgrade your site’s design, create a custom theme, create custom plugins, and more. Contact us for more information about how we can help you with all your website needs.

Top