November 23, 2022
Several purple shapes against a white background, with a purple squiggle arrow broken by a circle containing an exclamation point denoting an alert.

One error many WordPress users dread is the white screen of death with the message “error establishing a database connection.” This error occurs when there’s a disconnection between your WordPress website and its database. It's also one of the easiest WordPress errors to fix if you know what to do.

This article helps you identify the causes of this error and how to restore your WordPress database connection.

Keep reading to learn the following:

WordPress database connection and how it works

Whenever you build a new WordPress website, it usually creates and connects to a database automatically. WordPress abstracts the process to the background because you don’t need to know how it works for your website to function.

However, basic database knowledge can go a long way, especially if you need to create a custom database for your new website. It also helps to learn if you need to connect that website to a pre-existing database if, for example, you’re migrating to a new host.

So how does a database work?

Your WordPress database usually stores all the data on your WordPress except your media content, like videos, audio, and images. It does not store theme and plugin files, including core WordPress files (like wp-login.php).

But it stores page data, post data, meta information, and login information.

WordPress uses MySQL, an open-source software, as its database management system. MySQL is responsible for how your database stores information and gives you access. It helps you store, change, and delete data from your database using MySQL queries.

It’s pretty easy to access your database directly and run different MySQL queries, or you can use a database management software like phpMyAdmin to simplify the process. That way, you can perform some specialized tasks faster or take actions you can’t get from your dashboard.

So what happens when the connection between a WordPress website and its database breaks? Your website will display an “error establishing a database connection” message.

What happens when you experience an error establishing a database connection in WordPress?

The first thing you’ll see when you experience this error message is what many WordPress users call a “White Screen of Death.” Besides the error message, all you’ll see is a blank white or gray page.

Screenshot of Error Establishing a Database Connection Page.

That’s because your website cannot retrieve data from your database and display your webpages.

Moreover, because there’s a broken connection with your database, you won’t just have a white screen. You’ll experience problems trying to access your WordPress dashboard. You won’t be able to make any changes to your WordPress themes or plugins or upload any content or media.

How about your website visitors? If you’ve cached your website, they may not see this error immediately. Instead, they’ll still have access to your cached pages for a short period until it expires. Afterward, they’ll see a 500 HTTP error code or the message “internal server error.”

Although relatively easy to fix, a database connection error may cost your business plenty of money. So what causes this error?

Reasons you may experience an error establishing a database connection in WordPress

Any error establishing a database connection is usually a result of several issues:

  • The most common issue is incorrect database login details. Your WordPress website installation uses separate login information to connect to its MySQL database. If this information changes or is inaccurate, your website cannot link to its database. Then, it throws this error.
  • Your database may be corrupted, leading to a WordPress database connection error. Installing and deleting many themes and plugins can clutter your database and corrupt some database tables. Sometimes, some tables may be deleted by accident.
  • If you interrupt the WordPress installation process, you might inadvertently corrupt some core WordPress files. Also, malicious actors and web attacks by hackers can corrupt your database connection, leading to an error.
  • Sometimes, your database server may be experiencing downtime.
  • A sudden spike in web traffic on a shared WordPress hosting plan can cause your website to throw a database connection error.

So how do you identify and fix the problem causing the error establishing a database connection?

How to fix the error establishing a database connection in WordPress

Fixing a database connection error is pretty straightforward if you know where to look. Here are some common solutions you can try out.

1. Ensure your database login credentials are correct

Since this is the most common reason for a broken WordPress database connection, always start by confirming that your database login credentials are correct. Most times, migrating your WordPress website to a new hosting service may be the culprit.

To check these details, you must first access the wp-config.php file. You can do this using a secure FTP client or browse the root files of your website using cPanel.

Once you identify the wp-config.php file, right-click to edit it:

// ** MySQL settings - You can get this info from your web host ** //
/** The name of the database for WordPress */
define( 'DB_NAME', 'wptest' );

/** MySQL database username */
define( 'DB_USER', 'wpadmin' );

/** MySQL database password */
define( 'DB_PASSWORD', '**************' );

/** MySQL hostname */
define( 'DB_HOST', 'localhost' );

You’re looking for three unique values:

  • Database name.
  • Username.
  • Password.

Once you identify them on the wp-config.php file, double-check with the values on the server to ensure they match. If they don’t, edit the values on the server side to match what you have in the wp-config.php file. Save these changes, and that resolves the connection problem.

2. Repair your database if it’s corrupted

Although less common, you may attempt to access your website’s backend and instead receive this database error in WordPress:

“One or more database tables are unavailable. The database may need to be repaired.”

Although you’ll see the standard database connection error on your front end, this message will appear on your WordPress backend. It may be because of adding and removing different themes and plugins over extended periods.

To resolve it, you can initiate a unique inbuilt WordPress feature: database repair mode. Here’s how:

  • Open your wp-config.php file

Add define('WP_ALLOW_REPAIR', true); to your wp-config.php file and save.

Image of wp-config.php File with the Allow Repair Query.

Screenshot of Database Repair Utility.

Once done, go back to your wp-config.php file and delete the define('WP_ALLOW_REPAIR', true); query. That prevents anyone from accessing the database repair page after you’re done.

3. Check if your database server is down

If that fails, check with your hosting provider and determine if your database server is down. There are several reasons this could happen:

  • If too much traffic comes into the website and your hosting provider cannot handle it, that may cause a database connection break.
  • Your hosting provider is upgrading its servers and systems.
  • Using shared resources, your database may have too many concurrent connections. Since many hosts put connection limits on their servers, simultaneous connections to your database may cause a break.
  • If you’re on shared hosting and someone else is using a considerable portion of your resources, that may cause your website to break.

If your website consumes too many resources, your hosting provider will probably contact you first or throttle your usage. A quick call or email to their customer service will get them to lift your restrictions or increase your resource allocation.

If your hosting provider is upgrading their systems, please be patient. The error should clear automatically once the upgrades are done.

4. Contact your hosting provider

If you don’t know what action to take, you can contact your service provider and ask them to address it. Most hosting providers have 24/7 customer support; you can call, email, text, or live chat with a customer agent about your issue.

They’ll usually clear any database error in WordPress for you or assign a technical expert to address it.

Bottom line

Fixing an error establishing a database connection in WordPress is not as difficult as you think. The most common reason for this error is incorrect database login details. Once you set the correct credentials in place, this problem goes away.

If you host your website with Nexcess, you won’t have to worry about broken database connections. Contact our customer support services, and an agent will help you resolve any issue you may have.

Consider hosting with Nexcess

Want to take your business to the next level? Sign up for the Nexcess fully managed WordPress hosting plan. We focus on building and maintaining your WordPress website and let you focus on growing and expanding your business.

Kiki Sheldon
Kiki Sheldon

Kiki works as a Security Specialist for Liquid Web. Before joining the Abuse & Security Operations Department, she worked on the Liquid Web Managed Hosting Support Team, where she gained extensive knowledge of Linux System Administration and popular Content Management Systems (CMSs).

Kiki’s passion for writing allows her to share her professional expertise and help others. She keeps up with technology and always looks to improve her technical skills. In her free time, she enjoys reading, especially classic books and detective stories.

We use cookies to understand how you interact with our site, to personalize and streamline your experience, and to tailor advertising. By continuing to use our site, you accept our use of cookies and accept our Privacy Policy.