“Error establishing a database connection” in WordPress: what wp-admin tells you that visitors never see

What does “Error establishing a database connection” mean?

Every WordPress page is built from the database. When WordPress cannot log in to it, find it or read from it, it stops and shows “Error establishing a database connection” instead of your site.

A site that is down this way is one of the fixes on our WordPress care and fixes page. We find the cause first, then fix it on the live site with a backup in hand.

How did we test it?

On 13 Oct 2026 we ran WordPress 7.1.3 on PHP 8.3 and Apache in Docker, with a MariaDB 11 database next to it. We broke one thing at a time and requested four addresses: the home page, /wp-admin/, the login page and the REST API.

The fifth fault was the wp_options table, renamed so WordPress could not find it.

What did visitors see for each fault?

The same page, five times out of five.

The REST API returned the same HTML page, not JSON.

Why does /wp-admin/ show more?

WordPress’s dead_db() function checks whether the request is for wp-admin. If it is, it prints the full error WordPress recorded while connecting. Anywhere else it prints only the short heading (dead_db() in the WordPress docs, lines 5617 to 5622 of functions.php in 7.1.3).

So open yoursite.com/wp-admin/ first; you do not need to be logged in. In our lab it split the faults into three groups:

1. Login or server problem. The password is wrong, the host is wrong, or the server is down. The message names the host it tried.
2. Wrong database name. “Cannot select database” means the login worked.
3. Missing or damaged tables. The login and the name are fine, and something is wrong inside the database. Back up before touching it.

Is it the database server or wp-config.php?

If wp-admin shows the first message, ask your host whether the database server is up before you edit anything. When we started our database again, the site came back within the 8 seconds we waited, with no change to any file.

If the host says the server is fine, compare DB_NAME, DB_USER, DB_PASSWORD and DB_HOST in wp-config.php with the database details in your hosting panel. We covered other wp-config.php settings that can lock you out in the WordPress Address and Site Address post.

After a move, $table_prefix in the same file matters too. If it changed and the rows inside the tables did not, the site loads but wp-admin answers “Sorry, you are not allowed to access this page”. We traced that one in the table prefix fix.

Why did our first wrong password not break the site?

On our first pass we put a wrong password in wp-config.php and the site still loaded. PHP’s opcode cache was still serving the old file: this server checks for changes every 2 seconds (opcache.revalidate_freq=2), and our request came sooner.

With a 4 second wait after each edit, every fault showed up. Give a change a few seconds before you judge it.

Should you turn on WP_DEBUG?

Be careful. With WP_DEBUG on and a wrong password, the error page changed in two ways.

It printed “Access denied for user ‘wpuser’@’172.21.0.3′” and the file path /var/www/html/wp-includes/class-wpdb.php to anyone who loaded the home page. And it returned status 200, not 500. An uptime check that only looks for 200 would have marked the broken site as up.

If wp-admin already told you the cause, leave WP_DEBUG off. If you do turn it on, turn it off again within minutes. The WordPress debugging docs cover logging to a file.

The memory error that shows “There has been a critical error on this website” is a different problem with a different fix; we traced it in WordPress memory exhausted and the critical error.

Can visitors see a better page while you fix it?

Yes. WordPress loads wp-content/db-error.php, if it exists, in place of its own page. We added one that sends status 503, a Retry-After header of 300 seconds and a short “We will be back in a few minutes” message. With the database stopped, every address we tried showed it.

One catch from the lab: it also replaced the /wp-admin/ message, so the diagnosis above was gone. Read wp-admin first, then add the file.

This is a fix we do as a one-off job. We read the wp-admin message, check the database with the host, correct wp-config.php or repair the tables, and leave a 503 page in place so search engines know to come back.

What did we not test?

• MySQL itself. Our database was MariaDB 11.
• “Too many connections” when a busy server runs out of connections.
• A table that is crashed and needs REPAIR, as opposed to missing. We did not try the WP_ALLOW_REPAIR screen.
• Multisite, database hosts given as a socket or a port, and a full disk on the database server.
• A real hosting control panel. We edited wp-config.php directly.

Is your site showing this error right now?

Send us the message from yoursite.com/wp-admin/, and we will tell you which of the three it is and what it takes to fix.