Blog

How to fix “Error establishing a database connection”

Ink sketch of a stack of database disks next to an unplugged cable, with a green light on the top disk.

“Error establishing a database connection” means WordPress could not reach the MySQL or MariaDB database that holds your posts, pages, users and settings. The usual causes are a wrong database name, username, password or host in wp-config.php, a database server that is down or at its connection limit, and damaged tables. To find out which one you have, open yoursite.com/wp-admin/. Visitors only see the short message, but the admin area shows a longer one that names the problem.

This guide explains where the message comes from, what we saw when we broke a test site in each of these ways, and how to fix each cause.

What does “Error establishing a database connection” mean?

WordPress keeps almost everything in a database: posts, pages, menus, users, plugin settings and, on a store, orders. Your theme and plugin files live on the disk, but without the database WordPress has nothing to show. So when the database does not answer, WordPress stops and shows this message instead of a page.

In plain words, the website and its database have stopped talking to each other. Your content is usually still there. The connection is what broke.

Where does the message come from in WordPress?

We read the WordPress source to see how the message is built. It comes from two places that work together:

  1. The database class. The file class-wpdb.php tries to connect with the details from wp-config.php. When the connection fails, it writes a detailed message. That message says the username and password may be wrong, or the database server at your host name could not be reached, and it asks three questions: is the username and password correct, is the host name correct, and is the database server running?
  2. The dead_db() function. This function in functions.php decides who sees what. In the admin area it shows the detailed message. Everywhere else it shows only the short heading “Error establishing a database connection”.

Both send an HTTP 500 status. The source code says that is on purpose, so search engines do not store the error page in place of your real one. If a file named db-error.php exists in your wp-content folder, WordPress shows that file instead of either message.

What did we see when we broke a test site on purpose?

We ran a fresh WordPress 7.1.4 site with a MariaDB 11 database in Docker. Then we broke one thing at a time, loaded the home page and /wp-admin/, and wrote down what each one showed. Debugging was off, as it should be on a live site.

What we broke Home page /wp-admin/
Wrong password in wp-config.php Short message, status 500 The long message, which says the username and password in wp-config.php are wrong or the database server could not be reached
Wrong database username Short message, status 500 Same as a wrong password
Wrong database host Short message after about four seconds Same as a wrong password
Database server stopped Short message after about four seconds Same as a wrong password
Wrong database name Short message, status 500 “Cannot select database”, which says the username and password are fine but the database could not be selected
Main settings table missing Short message, status 500 “One or more database tables are unavailable. The database may need to be repaired.”
Database at its connection limit Short message, status 500 Same as a wrong password, even though the password was right
Wrong table prefix in wp-config.php No error. Both pages sent us to the WordPress install screen. Install screen

Three things stand out:

  • Visitors see the same short message whatever the cause. The home page tells you nothing. The admin message is the one to read.
  • The admin message can mislead. When we filled every allowed connection on the database server, the admin page still blamed the username and password. If you are sure the details are right, suspect the server.
  • A wrong host or a stopped server was slow to fail. In our test those two took about four seconds before the error appeared, because WordPress waited for a server that never answered. A wrong password failed at once. On your hosting the wait can be different, but a slow error does point at the server rather than the password.

Once we put each setting back, the site loaded normally with all its content. Nothing was lost in any of these tests.

How do you check the database details in wp-config.php?

Most of the time the cause is a detail in wp-config.php that does not match the database. WordPress’s own list of common WordPress errors puts an incorrect wp-config.php first. Open the file in your hosting file manager. It sits in the folder where WordPress is installed, usually public_html. Find these four lines:

define( 'DB_NAME', 'database_name_here' );
define( 'DB_USER', 'username_here' );
define( 'DB_PASSWORD', 'password_here' );
define( 'DB_HOST', 'localhost' );

Then compare each one with what your hosting control panel shows. On cPanel hosting, open Manage My Databases, which older cPanel versions call MySQL Databases. cPanel’s guide to managing your databases describes each part of that screen.

  1. Database name. When your host has database prefixing turned on, cPanel puts your account username and an underscore in front of every database name, for example accountname_wp. WordPress’s own “Cannot select database” message points out this prefix too. A name typed without it will not match. Copy the name exactly as the Current Databases table shows it.
  2. Username. Copy it exactly as the Current Users table shows it.
  3. The user’s access to the database. In the Current Databases table, check that your database user appears under Privileged Users for that database. If it does not, add it in the Add User To Database section and tick ALL PRIVILEGES.
  4. The password. If you are not sure it matches, click Change Password next to the user in the Current Users table, set a new one, then paste the same password into DB_PASSWORD. Copy it exactly, with no space before or after it inside the quotes.
  5. The host. On most cPanel hosting the database runs on the same server, so DB_HOST is localhost. Only change it if your host gives you a different address.

Save the file and reload the site. Keep a copy of the original wp-config.php before you edit it, so you can put it back if you make things worse. The WordPress handbook page on editing wp-config.php explains every setting in the file.

Did the error start right after moving your site?

This is the most common time to see it. When you move WordPress to a new host, you create a new database and user there, and wp-config.php still holds the old host’s details until you change them. Our guide to moving your site lists the three values to change, DB_NAME, DB_USER and DB_PASSWORD, and says to leave DB_HOST as localhost.

If the details match and the error remains, check that the database import actually finished. In phpMyAdmin, open the database and look for the WordPress tables, which start with wp_ or your own prefix. An empty database gives you the install screen, not this error, as our test showed.

What if the details are right and it still fails?

Then the problem is on the database server, not in your files. WordPress’s list of common errors names two hosting causes: the database has hit its quota and been shut down, or the server is down. Our connection limit test adds a third. A database server only accepts a set number of connections at once. A traffic spike, an aggressive bot or a stuck plugin can use them all up, and every new page load then fails.

Signs that it is the server:

  • The error comes and goes, and the site loads fine a minute later.
  • Other sites on the same hosting account show the same error.
  • phpMyAdmin also fails to open the database.
  • The error shows up when the site is busiest.

You cannot fix these from WordPress. Contact your host, say when the error appeared, and ask whether the database server was down, over its limit or over quota. If it happens every time traffic rises, a page cache helps, because cached pages are served without a database query at all.

How do you repair damaged database tables?

If /wp-admin/ says “One or more database tables are unavailable. The database may need to be repaired”, WordPress can connect but cannot read a table it needs. WordPress has a built-in repair page for this:

  1. Take a backup of the database first, from your hosting backups or phpMyAdmin’s Export.
  2. Add this line to wp-config.php, above the line that says “That’s all, stop editing”:
    define( 'WP_ALLOW_REPAIR', true );
  3. Open yoursite.com/wp-admin/maint/repair.php and click Repair Database.
  4. Remove the line from wp-config.php as soon as the repair finishes.

Step 4 matters. The wp-config.php handbook page warns that the repair page works without logging in, because a damaged database often stops you from logging in. While the line is there, anyone who knows the address can run it.

cPanel also has a Repair Database option on the same database screen. If neither one can fix a table, or the table is missing entirely rather than damaged, restore the database from a backup taken before the problem started.

Why do you see the WordPress install screen instead?

If your site suddenly shows “WordPress Installation” instead of an error, WordPress connected to the database but found no tables with the prefix set in wp-config.php. The line looks like this:

$table_prefix = 'wp_';

Check the real prefix in phpMyAdmin. If your tables start with something like wpx7_, the prefix in wp-config.php must say wpx7_ too. Do not run the installer to make the screen go away. That creates a second, empty site next to your real data.

Should you turn on WP_DEBUG to see the real error?

Only briefly, and only if you can switch it off again right away. With WP_DEBUG set to true in our test, the home page showed the raw database error to every visitor. With a wrong password it read “Access denied for user” followed by the database username, and it also showed the path of the WordPress file on the server. WordPress’s debugging guide says debug tools are not recommended on live sites.

The /wp-admin/ message already tells you most of what you need, without exposing anything. If you need more, use WP_DEBUG_LOG with WP_DEBUG_DISPLAY set to false. That writes errors to wp-content/debug.log instead of the page. Delete the log when you are done.

Can a hacked site cause this error?

It can. A hacked site may have a changed wp-config.php, or malware that floods the database. WordPress’s list of common errors says to check for a compromise once you have ruled out wp-config.php and the host. If you find unknown files, unknown admin users or a wp-config.php you did not edit, follow our guide on what to do when your WordPress site is hacked before you change the database password, so the attacker cannot simply read the new one.

How do you stop it from happening again?

  • Keep a working copy of wp-config.php outside public_html. Plugins and migrations sometimes rewrite it.
  • Keep backups you can restore. A recent database backup turns a damaged table into a short fix.
  • Use a page cache. Fewer database queries per visit means a busy hour is less likely to hit the connection limit.
  • Watch your site from outside. An uptime check that loads your home page every few minutes tells you about a 500 error before your customers do.
  • Remove plugins you do not use. Each active plugin can add database queries to every page.

If your site is on our WordPress hosting and the details in wp-config.php match cPanel, open a ticket with the time the error appeared and we will check the database server for you.

Frequently asked questions

What does “Error establishing a database connection” mean in simple words?

Your website could not talk to the database that stores its content. The content is usually still there. The connection details are wrong, or the database server is not answering.

Will I lose my posts and orders?

Usually not. The error means WordPress could not reach the database, not that the database was deleted. In our tests the site came back with all its content as soon as the connection worked again. Only damaged or missing tables need a repair or a backup.

Why does the error appear and disappear on its own?

That points at the database server, not your settings. It is often busy or at its connection limit during traffic spikes. Ask your host to check the database server at the times it happened.

What should DB_HOST be on cPanel hosting?

Usually localhost, because the database runs on the same server as the website. Use a different value only if your host gives you one.

How do I see the real reason behind the error?

Open yoursite.com/wp-admin/. WordPress shows visitors only the short message, but the admin area shows a longer one that says whether the login details, the database name or the tables are the problem.

Category:

Written by

Muhammad Mairaj

Muhammad Mairaj

Muhammad Mairaj is a Senior Backend Engineer with 8 years building payment and data systems. He built Webstribe's card checkout and runs its servers. He is a Partner at Webstribe, a brand of Softstribe Solutions, and a Senior Software Engineer (Backend) at Funavry Technologies in Islamabad.

Hosting for your WordPress site

Yearly plans in rupees, with the same price at renewal. Free SSL and daily backups on every plan.