WordPress: Error establishing a database connection, step by step fixes

WordPress can't reach MySQL or MariaDB. Check wp-config.php credentials, a stopped database, corrupted tables and a full disk, with commands you can paste.

· 6 min read · By the Spot Downtime team

"Error establishing a database connection" is WordPress telling you it can't talk to MySQL or MariaDB. No database, no posts, no settings, so it shows this plain page instead of your site. The server answers with an HTTP 5xx status, so uptime monitors see it too.

Work from the cheapest check to the most invasive one. Most cases are one of four things: wrong credentials, a database server that isn't running, corrupted tables or a full disk.

1. Is only the front end broken, or the admin too?

Open /wp-admin. If it shows a different message, such as "One or more database tables are unavailable", the connection works but tables are damaged (see step 5). If it shows the same error, keep going.

2. Check the database server is running

On a server you control:

bash
sudo systemctl status mysql        # or mariadb
sudo systemctl restart mysql
df -h                              # a full disk stops the database
free -m                            # low memory can get mysqld killed
sudo journalctl -u mysql --since "1 hour ago" | tail -50

A database that keeps stopping is often killed by the kernel when the server runs out of memory. Look for "Out of memory" or oom-killer lines in dmesg. If the disk is full, free space first (old logs and backups are the usual culprits), then restart the database. On shared hosting you can't restart it yourself, so contact the host and ask whether the database server has had problems.

3. Test the credentials from wp-config.php

Open wp-config.php in the WordPress root and look at these four lines:

php
define( 'DB_NAME', 'wordpress' );
define( 'DB_USER', 'wp_user' );
define( 'DB_PASSWORD', '...' );
define( 'DB_HOST', 'localhost' );

Then try them yourself, using the same values:

bash
mysql -u wp_user -p -h localhost wordpress
# Wrong password -> "Access denied for user"
# Wrong database  -> "Unknown database"
# Server down     -> "Can't connect to MySQL server"

The message tells you which line to fix:

  • Access denied: the user or password is wrong, or the user lost its privileges. Reset the password and update wp-config.php.
  • Unknown database: DB_NAME is wrong, or the database was dropped during a migration or restore.
  • Can't connect: the host is wrong or the server isn't reachable. After moving to a new host, DB_HOST is often not localhost any more. Managed databases use a hostname, sometimes with a port such as db.example.com:3306.

The usual trigger is a change: a migration, a password rotation, a restored backup with an old wp-config.php, or a host that moved your database to another server.

4. Too many connections

A traffic spike, a bot, or a plugin that holds connections open can use up MySQL's connection limit. New visitors then get the error while existing ones don't. Check from the database:

sql
SHOW VARIABLES LIKE 'max_connections';
SHOW STATUS LIKE 'Threads_connected';
SHOW FULL PROCESSLIST;

Look for many identical slow queries and fix the cause (a plugin, a missing index, bot traffic) rather than only raising the limit. Page caching helps because cached pages never touch the database.

5. Repair corrupted tables

A crash or a full disk can leave tables damaged. If you have WP-CLI, check them from the server:

bash
wp db check
wp db repair

Without WP-CLI, add this line to wp-config.php, then open /wp-admin/maint/repair.php:

php
define( 'WP_ALLOW_REPAIR', true );

Remove the repair line afterwards

The repair page works without logging in while that constant is set. Delete the line as soon as you're done. Take a database backup first if you can: repairs are usually safe, but not always reversible.

6. If the files were hacked or replaced

If credentials are right and the database is healthy but the error persists, check that wp-config.php exists and is readable, that it wasn't replaced by a blank file, and that nothing outside WordPress changed the database host in the options table. Compare against a backup, and change database and admin passwords if you suspect a compromise.

Prevent it from coming back

  • Keep database backups off the server and test a restore, so a corrupted table is an annoyance and not a disaster.
  • Watch disk space and memory. Both failing quietly is the most common reason a database stops overnight.
  • Add page caching so a traffic spike doesn't turn into hundreds of simultaneous database connections.
  • After any migration or credential rotation, load the site once and check the monitor before you walk away.

A quick order of operations

  1. Is the database running and the disk not full? Restart it if needed.
  2. Do the credentials in wp-config.php work from the command line?
  3. Is the server at its connection limit?
  4. Do the tables pass wp db check?

Don't wait for a customer to tell you

This error often appears at night or after an automated update, and caching can hide it for a while on some pages. Monitor the home page with a status code check and a keyword that only a working page contains, so a cached or error page is never counted as healthy. Our WordPress monitoring guide walks through the setup, and website monitoring sends the alert to the channel your team actually reads. If the site is already down, the website down checklist covers the general triage.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading