WordPress "Error Establishing a Database Connection": How to Fix It

"Error establishing a database connection" is WordPress telling you that PHP is running but it could not log in to MySQL or MariaDB. The web server is fine, the files are fine, and WordPress cannot read a single post, option or user. Because the front end and the admin both need the database, the whole site goes down at once, usually with an HTTP 500 status and a plain white page carrying that sentence.

This guide walks through the causes in the order they are most likely, with the exact commands and settings to check each one.

What the error actually means

WordPress connects to the database very early, in wp-includes/wp-db.php (the wpdb class). If the connection fails, it stops and prints the message. There are only four real reasons:

1. The credentials or host in wp-config.php are wrong.
2. The database server is not running or not reachable.
3. The database server is running but refusing or dropping connections (limits, overload, a full disk).
4. The database itself is damaged, or the tables WordPress expects are missing.

A fifth case looks the same but is different: the front end shows the error and /wp-admin/ shows "One or more database tables are unavailable". That is corruption, covered in the repair section below.

Step 1: Confirm it is the database, not something else

First check what your server returns. The HTTP Status Checker shows the real status code and headers from outside your network. A database failure normally returns a 500. If you get a 502, 503 or 504, start with why is my website down instead, because the problem is probably the web server or PHP, not MySQL.

If you have shell access, the quickest test of the database is to connect with the same credentials WordPress uses:

mysql -h localhost -u DB_USER -p DB_NAME -e "SELECT 1;"

If that works, the database and credentials are good and the problem is elsewhere (see the host limits section). If it fails, the error message tells you which of the first three causes you have:

Step 2: Check wp-config.php credentials

Open wp-config.php in the site root and find these four constants:

define( 'DB_NAME', 'wp_example' );
define( 'DB_USER', 'wp_user' );
define( 'DB_PASSWORD', 'secret-password' );
define( 'DB_HOST', 'localhost' );

Typical mistakes:

• A migration or restore changed something. Moving a site to a new host almost always changes the database name, user, or password. The old values copied from the old server will not work.
• A password was reset in the hosting panel or in MySQL without updating wp-config.php.
• A special character was mishandled. Passwords containing a single quote or backslash must be escaped inside a single-quoted PHP string. Use a password generator that avoids quotes and backslashes, or escape them.
• DB_HOST is not localhost. Many managed hosts and cloud databases use a hostname such as db.example-host.com, or a host with a port (db.example.com:3306) or a socket (localhost:/var/run/mysqld/mysqld.sock). Your host's documentation gives the exact value.
• Trailing whitespace or a curly quote pasted from a document.

If WP-CLI is available, wp db check and wp config get DB_HOST read the same values from wp-config.php and test them safely.

Step 3: Is MySQL or MariaDB running?

On a VPS or dedicated server you control, check the service:

sudo systemctl status mysql        # or: mariadb
sudo journalctl -u mysql -n 100 --no-pager
sudo tail -n 100 /var/log/mysql/error.log

If it is stopped, start it with sudo systemctl start mysql and then read the log to learn why it stopped. The most common reasons:

• Out of memory. The Linux OOM killer ends mysqld first because it is the largest process. Look for Out of memory: Killed process ... (mysqld) in dmesg -T or journalctl -k. Fix by adding RAM or swap, lowering innodb_buffer_pool_size, or reducing PHP-FPM workers.
• Disk full. MySQL cannot write and either crashes or refuses connections. Run df -h and df -i (inodes). Clear old logs, backups and cache directories.
• InnoDB crash recovery. After a hard shutdown MySQL may take a long time to replay logs. Wait before restarting it repeatedly.

You can also confirm the port is reachable with the Port Checker against 3306, though most hosts deliberately keep that port closed to the internet, so a closed result from outside is normal when the database is on the same server as the site. Test from the web server itself with nc -vz DB_HOST 3306 when the database is on a separate machine.

Step 4: Host limits and shared hosting causes

If your own credentials test fine from the command line but visitors intermittently see the error, you are probably hitting a limit.

• Max connections. Every PHP request opens a connection. Traffic spikes, crawlers, or a slow query that holds connections open can reach max_connections (check with SHOW VARIABLES LIKE 'max_connections'; and SHOW STATUS LIKE 'Threads_connected';). On shared hosting you cannot change it, and the host's own limit per user may be much lower. Add page caching so fewer requests reach PHP and the database, and block abusive bots.
• Per-user resource limits. Shared hosts using CloudLinux and similar tools throttle accounts that exceed CPU, memory or entry-process limits, and the symptom is often this error. Your control panel usually shows a resource usage graph with the limit hits.
• Account suspended or database quota exceeded. An overdue invoice or a database that outgrew its quota will lock the user out.
• Remote database latency or outage. If the database is on a separate server, the problem may be the network between the two machines.

Open a support ticket if you suspect any of these. Give the exact time (with timezone) of the errors and ask whether the account hit a limit then. The Website Hosting Checker tells you who actually hosts the site, which helps when you are routing the ticket.

Step 5: Repair mode with WP_ALLOW_REPAIR

If the database connects but tables are corrupted (symptoms: "One or more database tables are unavailable", the front end showing this error while credentials are correct, or queries failing after a crash), use WordPress's built-in repair tool.

Add this line to wp-config.php, above the line that says "That's all, stop editing":

define( 'WP_ALLOW_REPAIR', true );

Then visit:

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

The page offers "Repair Database" and "Repair and Optimize Database". Run the first, then check the site.

With WP-CLI, the equivalent is:

wp db check
wp db repair
wp db optimize

Or with MySQL's own tool: mysqlcheck -u root -p --auto-repair --databases wp_example. Note that REPAIR TABLE only works for MyISAM tables. Most modern WordPress sites use InnoDB, where a corrupted table usually needs a backup restore, or MySQL's innodb_force_recovery option to dump the data. Before attempting any repair, take a copy of the database files or run mysqldump if the server allows it.

Step 6: Wrong table prefix or missing tables

If the connection works but WordPress still reports the error, or shows the installation screen, check $table_prefix in wp-config.php against the real tables:

wp db query "SHOW TABLES;"

If the tables are named wp7x_posts and your config says $table_prefix = 'wp_';, WordPress finds nothing. Setting the correct prefix fixes it. Also look at the siteurl and home rows in the options table, since wrong values there cause different symptoms (see the too many redirects guide).

Step 7: Recover from a bad state

If nothing above works, restore the latest database backup with mysql -u user -p dbname < backup.sql, into the existing empty database so the credentials in wp-config.php stay valid. Then find out why it failed: a repeat points to memory pressure, a bot flood or an undersized plan.

Prevent the error from catching you out

• Monitor the site with an HTTP check and a keyword check, so you are alerted within minutes. The uptime monitor can search for a phrase that should appear on your home page and alert when it does not, which catches database errors that still return a 200 on some setups.
• Keep a daily database backup stored off the server, and test a restore at least once.
• Use page caching so that most visitors never touch MySQL.
• Keep an eye on disk space and memory on self-managed servers.
• See WordPress memory limit exhausted if PHP errors accompany the database problems, and WordPress plugin conflict troubleshooting if the trouble began after an update.

Next steps

• Run the Website Health Check to confirm the site status after a fix.
• Verify the response code with the HTTP Status Checker.
• Set up alerts with the uptime monitor so the next outage reaches you first.
• Use the Outage Root Cause Finder when you are not sure whether DNS, hosting or the application is to blame.
• Read fix 500 internal server error for the generic version of this failure.

FAQ

Why does only /wp-admin show the database error but the front end works?

That is usually table corruption or a missing table that the admin needs but the cached front end does not. Enable WP_ALLOW_REPAIR, run the repair page, and remove the constant afterwards.

Can too much traffic cause this error?

Yes. Each uncached request opens a database connection, and when the server reaches its max_connections or your host's per-account limit, new requests fail with this message. Page caching and bot blocking reduce the load.

Is it safe to leave WP_ALLOW_REPAIR enabled?

No. The repair page does not require authentication while the constant is set, so anyone could trigger repair and optimize operations. Remove it from wp-config.php once the repair is finished.

I changed nothing, so why did it suddenly break?

Something changed on the server side: MySQL was killed for low memory, the disk filled up, the host rotated the database password, or a maintenance window restarted the service. Check the MySQL error log and ask your host.

Will reinstalling WordPress fix it?

Rarely. Reinstalling core files does not touch the database or wp-config.php, which are the usual causes. Fix the credentials or the database itself first.

This page is general information written by our editorial team and updated when documentation changes. Servers and providers differ, so test changes safely first. See our editorial policy and disclaimer.